Seedance 2.5 API 가이드: 코드 또는 AI Agent로 영상 생성하기

Seedance 2.5는 텍스트와 참조 소재로 영상을 생성하는 뛰어난 모델입니다. 현재 접근 방식은 pre-release이며 provider를 통해 중개되는 형태로, 아직 정식으로 공개되지 않았습니다. 따라서 아래 내용은 모두 예상 동작으로 간주하고, 출시 전에 provider와 확인하시기 바랍니다. 이 글은 독립적인 가이드이며, EvoLink는 저희가 추천하는 서드파티 provider입니다(저희는 ByteDance와 아무런 제휴 관계가 없습니다). 요청 구조는 EvoLink의 API를 따릅니다. 프로덕션에 적용하기 전에 해당 문서와 대조하여 확인하세요.

준비하기

EvoLink에서 API key를 생성하고 잔액을 충전한 뒤 key를 export하면 테스트를 시작할 수 있습니다.

export EVOLINK_KEY="sk-..."

과금은 아직 공개된 요금이 없습니다. 출력 초 단위로 과금될 것으로 예상되며, 네이티브 오디오는 추가 비용 없이 포함되고, content_filter를 끄면 약 1.1배의 비용이 발생할 것으로 예상됩니다. 개발 전에 provider 콘솔에서 현재 모델을 확인하세요.

생성 요청

모델 id는 seedance-2.5-reference-to-video입니다(pre-release이므로 provider가 확정하면 교체할 수 있도록 설정 가능한 상태로 유지하세요).

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer $EVOLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-reference-to-video",
    "prompt": "golden-hour drone pullback over a coastal city, anamorphic flare",
    "duration": 5,
    "quality": "720p",
    "generate_audio": true,
    "content_filter": true
  }'

각 필드 설명:

• model — 위의 pre-release 버전 id입니다. 설정 가능한 상태로 유지하세요.
• prompt — 샷에 대한 텍스트 설명입니다.
• duration — 초 단위이며 예상 범위는 4–30입니다(기본값 5). 상한은 provider에 확인하세요.
• quality — "480p" 또는 "720p"입니다(기본값 "720p"). 1080p 등 더 높은 해상도는 provider 문서에서 확인되기 전까지 미정입니다. 지원된다고 가정하지 마세요.
• generate_audio — 불리언, 기본값 true. 네이티브 오디오는 한 번의 생성에 포함되며 추가 비용이 없습니다.
• content_filter — 불리언, 기본값 true. false로 설정하면 약 1.1배로 과금될 것으로 예상됩니다.
• image_urls(≤30), video_urls(≤10), audio_urls(≤10) — 참조 파일이며 자세한 내용은 아래를 참고하세요.
• callback_url — 완료 알림용 선택적 webhook입니다.

API는 태스크를 반환하며, 이후 polling을 진행합니다.

{ "id": "task_8f2c...", "status": "pending" }

전체 파라미터 설명은 저희 API 페이지에서 확인할 수 있습니다.

polling으로 결과 가져오기

상태가 completed가 될 때까지 태스크 상세 엔드포인트를 polling합니다.

curl "https://api.evolink.ai/v1/task-detail?id=task_8f2c..." \
  -H "Authorization: Bearer $EVOLINK_KEY"

status는 pending → processing → completed(또는 failed) 순으로 진행됩니다. completed가 되면 반환된 영상 URL을 다운로드하세요.

Node 예제

fetch 기반의 최소 구성 플로우입니다. 먼저 제출하고, 그다음 polling합니다.

const KEY = process.env.EVOLINK_KEY;
const BASE = "https://api.evolink.ai/v1";
const MODEL = "seedance-2.5-reference-to-video"; // pre-release, keep configurable

async function generate() {
  const res = await fetch(`${BASE}/videos/generations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: MODEL,
      prompt: "the character walks through a market at dusk",
      duration: 5,
      quality: "720p",
      generate_audio: true,
      content_filter: true,
    }),
  });
  const { id } = await res.json();
  return id;
}

async function poll(id) {
  while (true) {
    const res = await fetch(`${BASE}/task-detail?id=${id}`, {
      headers: { "Authorization": `Bearer ${KEY}` },
    });
    const task = await res.json();
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error("generation failed");
    await new Promise((r) => setTimeout(r, 5000));
  }
}

const id = await generate();
const done = await poll(id);
console.log(done);

참조 파일

참조 소재는 타입별로 나누어 URL 리스트 형태로 첨부할 수 있습니다.

• image_urls — 이미지 최대 30장.
• video_urls — 영상 최대 10개.
• audio_urls — 오디오 클립 최대 10개.

{
  "model": "seedance-2.5-reference-to-video",
  "prompt": "the character walks through the market, camera following the uploaded drone move",
  "image_urls": [
    "https://cdn.example.com/character_front.png",
    "https://cdn.example.com/character_profile.png"
  ],
  "video_urls": ["https://cdn.example.com/drone_move.mp4"],
  "audio_urls": ["https://cdn.example.com/score_draft.mp3"],
  "duration": 5,
  "quality": "720p",
  "generate_audio": true
}

이미지는 캐릭터의 정체성과 색감을 고정하고, 영상 클립은 카메라 무브와 모션 스타일을 제공하며, 오디오는 템포를 이끕니다. 이를 활용하는 prompt 패턴은 프롬프트 라이브러리에서 실제 요청과 출력 결과로 확인할 수 있습니다.

프로덕션 환경에서의 비용 관리

아직 공개된 요금이 없으므로 아래 내용은 방향성 참고용으로만 삼고 provider 콘솔에서 확인하세요.

• 초안은 짧게, 완성본은 길게. 과금은 출력 초 단위로 계산될 것으로 예상되므로 duration이 가장 큰 비용 레버입니다. 짧은 초안으로 반복 작업한 뒤, 승인된 긴 테이크를 렌더링하세요.
• duration은 서버 측에서 제한하기. 자체 API 레이어에서 duration에 상한을 걸어, 버그가 재시도 루프 안에서 긴 테이크를 계속 렌더링하는 일을 방지하세요. 예상 범위가 4–30초라는 점을 기억하세요.
• content_filter에 유의하기. 기본값은 켜짐입니다. 끄면 청구액이 약 10% 늘어날 것으로 예상됩니다.
• 오디오는 무료. 네이티브 오디오는 추가 비용 없이 포함되므로 generate_audio: true로 설정해도 초 단위 계산은 달라지지 않습니다.

provider가 가격을 공개하면 가격 페이지에서 최신 수치를 재현하거나, 플레이그라운드에서 원하는 구성을 직접 가늠해 볼 수 있습니다.

AI Agent에 연동하기

사용 중인 Agent 프레임워크(Claude Agent SDK, Vercel AI SDK, LangChain 또는 MCP server)에서 REST 호출을 하나의 함수 도구로 감싸세요. prompt, duration, quality, generate_audio, content_filter, 그리고 참조 URL 리스트를 파라미터로 노출하면 됩니다. 이는 API 페이지의 계약과 그대로 대응합니다.

프로덕션 팁 하나: polling 단계는 생성 단계와 별도의 도구로 만드세요. 렌더링이 진행되는 동안 도구 슬롯을 점유하는 블로킹 호출보다, “태스크 X가 완료됐는지 확인”하는 방식을 Agent가 훨씬 매끄럽게 처리합니다. 권장 구조는 Agent 가이드를 참고하세요.

첫날부터 갖춰야 할 에러 처리

• 인증 / 잔액 오류 — 충전 링크와 함께 사용자에게 표시하세요. 무작정 재시도하지 마세요.
• 레이트 리밋 — 지수 백오프를 적용하세요. 부하가 높으면 렌더링 시간이 길어질 수 있습니다.
• failed 상태 또는 콘텐츠 정책 거부 — 반환된 사유를 로그로 남기세요. 이런 경우는 대개 prompt 문제이지 전송 계층의 버그가 아닙니다.

접근이 pre-release 단계이므로, 모델 id가 아직 내 계정에서 활성화되지 않은 경우도 처리해 두세요. 설정 가능한 상태를 유지하고, 프로덕션에 적용하기 전에 provider의 지원 여부를 확인하세요.

key를 발급받고 위 요청을 실행해 테스트를 시작하세요: API 퀵스타트 →