Discord 웹훅 파일 전송: files[0]에 영상 첨부하기

네, Discord 웹훅으로 파일을 보낼 수 있습니다. 웹훅 URL로 multipart/form-data POST를 보내면서, 파일은 파일 이름과 함께 이름이 files[0]인 파트에 넣고, 메시지 텍스트는 JSON으로 payload_json 파트에 넣으세요. Discord의 기본 업로드 한도는 파일당 20 MiB이므로, 먼저 영상 크기를 확인하고 한도를 넘으면 content에 영상 링크를 게시하세요.

Discord 관련 내용은 Webhook Resource, API Reference, Opcodes and Status Codes, Intro to Webhooks 페이지에서, Sume 관련 내용은 Run 웹훅 (영문)과 실행과 결과 (영문)에서 가져왔습니다. 모두 2026-09-28에 확인했습니다. Sume에는 Discord 봇이나 커넥터가 없습니다. 완성된 영상에 대한 Sume 웹훅은 여러분의 서버가 받고, 그다음 그 서버가 Discord를 호출합니다. 슬래시 커맨드로 영상을 시작하는 봇은 Discord 봇 AI 영상 생성에서 다룹니다.

Discord 웹훅으로 파일은 어떻게 보내나요?

Discord 서버 설정의 Integrations에서 웹훅을 만들고, 게시할 채널을 고른 뒤 웹훅 URL을 복사하세요. 그런 다음 그 URL, 즉 Discord의 Execute Webhook 엔드포인트로 HTTP POST를 보내세요.

• multipart/form-data 본문을 쓰세요. 파일마다 files[0], files[1]처럼 고유한 이름의 파트를 하나씩 두며, 각 파트에는 파일 이름이 담긴 Content-Disposition 헤더가 필요합니다.
• content 같은 파일 외 필드는 payload_json 파트 하나에 JSON으로 넣거나, 별도의 폼 필드로 보내세요.
• 메시지에는 content, embeds, components, file, poll 중 하나 이상이 있어야 합니다. content에는 최대 2000자까지 담을 수 있습니다.
• 생성된 메시지를 돌려받으려면 ?wait=true를 붙이세요. 붙이지 않으면 Discord는 204 No Content로 응답하며, 메시지가 저장되지 않았어도 오류를 반환하지 않습니다.

// Node 18+. DISCORD_WEBHOOK_URL is a secret: anyone holding it can post.
const LIMIT = 20 * 1024 * 1024; // Discord's default per-file limit, 20 MiB

async function postVideo(videoUrl, sizeBytes) {
  const hook = `${process.env.DISCORD_WEBHOOK_URL}?wait=true`;
  let res;
  if (sizeBytes > LIMIT) {
    res = await fetch(hook, { // too big to attach: send the link as JSON
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ content: `Your video is ready: ${videoUrl}` }),
    });
  } else {
    const video = await fetch(videoUrl); // a public media.sume.com URL
    if (!video.ok) throw new Error(`download answered ${video.status}`);
    const form = new FormData();
    form.append("payload_json", JSON.stringify({ content: "Your video is ready" }));
    form.append("files[0]", await video.blob(), "video.mp4");
    res = await fetch(hook, { method: "POST", body: form });
  }
  if (!res.ok) throw new Error(`Discord answered ${res.status}`);
  return res.json(); // the created message, because of wait=true
}

Discord 웹훅 파일 업로드 한도는 얼마인가요?

한도는 요청에 담긴 파일 하나하나에 적용됩니다. Discord 레퍼런스는 기본값을 20 MiB로 정하고 있으며, Nitro 상태나 서버의 Boost Tier에 따라 더 높을 수 있습니다. Discord의 JSON 오류 코드 40005의 메시지는 "Request entity too large. Try sending something smaller in size."(요청 엔터티가 너무 큽니다. 더 작은 크기로 보내 보세요)입니다.

MP4는 임베드 안에 넣을 수도 없습니다. 업로드한 파일은 아래 이미지 형식 중 하나일 때만 임베드에 쓸 수 있고, 웹훅은 임베드의 video 필드를 설정할 수 없습니다. 한도 안에 들면 영상을 파일로 첨부하고, 넘으면 링크를 게시하세요.

Discord 웹훅 URL은 시크릿인가요?

네, 비밀번호처럼 다루세요. Discord에 따르면 웹훅은 봇 사용자나 인증 없이 쓸 수 있으며, 토큰으로 웹훅을 조회·수정·삭제하는 호출에도 인증이 필요 없습니다. URL을 가진 사람은 누구나 그 웹훅의 이름으로 게시하거나 웹훅을 삭제할 수 있습니다.

URL은 서버 측 시크릿 저장소에 두고, 브라우저 코드나 모바일 앱, 공개 저장소에는 절대 두지 마세요. 유출되면 웹훅을 삭제하고 새로 만드세요.

Sume 영상이 준비되면 어떻게 게시하나요?

Sume 웹훅을 받는 서버에서, 그 웹훅을 검증한 뒤에 Discord를 호출하세요.

• Format 실행이 완료되거나 실패하면 Sume는 서명된 POST를 한 번 보냅니다. 느린 엔드포인트는 재시도를 받으므로, Discord를 호출하기 전에 원본 본문에 대한 HMAC-SHA256 서명을 검증하고, 이벤트를 기록하고, 10초 시도 시간 안에 2xx로 응답하세요. 검증 방법은 Sume 영상 실행용 서명된 웹훅에서 다룹니다.
• payload.artifacts[]의 각 항목에는 url, content_type, size_bytes가 담겨 있으므로, 아무것도 다운로드하기 전에 첨부할지 링크할지 정할 수 있습니다.
• media.sume.com URL은 내구성 있고 URL을 가진 누구에게나 공개됩니다. 다운로드에 API 키가 필요 없고, 게시한 링크는 만료되지 않습니다.
• 봉투의 request_id로 중복을 제거하세요. 이 값은 재시도마다 반복되므로, 재시도된 전달이 두 번 게시되지 않습니다.
• Discord URL을 Sume의 webhook_url로 등록하지 마세요. Sume의 POST에는 Discord 메시지가 아니라 실행 영수증이 담깁니다.