개발자가 지금 EvoLink를 통해 Seedance 2.5를 사용할 수 있나요?

네. 공식 API와 EvoLink 통합이 출시되었습니다. T2V, I2V, R2V model ID 중 하나를 선택하고 EvoLink 키를 생성한 뒤 짧은 테스트부터 시작하십시오.

Seedance 2.5 model ID를 하드코딩해도 되나요?

configurable하게 유지하십시오. 그래야 각 요청이 맞는 workflow를 선택할 수 있고, 애플리케이션이 Seedance 2.0을 rollback으로 유지할 수 있습니다.

로컬 mock은 무엇을 시뮬레이션해야 하나요?

최소한 작업 생성, pending, processing, completed, failed, 잘못된 요청, 키 누락, rate limit, 서버 불가, 중복 polling, 두 번 이상 도착하는 콜백을 시뮬레이션하십시오. 이는 회복력 시나리오이지 최종 Seedance 2.5 에러 계약에 대한 주장이 아닙니다.

로컬 스키마 테스트를 통과하면 통합이 프로덕션 준비가 된 건가요?

아닙니다. 로컬 테스트는 애플리케이션이 현재 계획 구조와 모델링된 상태 전이를 처리한다는 것만 증명합니다. 프로덕션 준비에는 추가로 provider 공식 스키마, 라이브 인증, 과금, 출력 조회, 지연, 실패, 품질 테스트가 필요합니다.

왜 Seedance 2.0을 폴백으로 쓰나요?

2.5 워크로드가 품질, 지연, 비용 기준을 놓쳤을 때 문서화된 rollback을 제공하기 때문입니다. 모든 2.5 요청을 2.0에서 안전하게 표현할 수 있는 것은 아니므로 폴백은 자격 기반이어야 합니다.

라이브 Seedance 2.5 경로인데 왜 HTTP 503을 mock하나요?

영상 애플리케이션은 provider와 무관하게 일시적인 업스트림 불가를 견뎌야 하고, mock은 라이브 작업을 소모하지 않고 그 경로를 저렴하게 연습하게 해 줍니다. 이 fixture는 회복력 테스트이지, Seedance 2.5 생성 엔드포인트가 정확히 그 응답을 문서화한다는 증거가 아닙니다.

Seedance 2.5 EvoLink 통합 가이드: 라이브 체크리스트

공식 Seedance 2.5 API와 EvoLink 통합이 출시되었습니다. 이제 provider 어댑터를 정의하고, 전송 타입을 생성하고, 도메인 payload를 검증하고, 비동기 작업을 제출하고, 대표적인 실패를 테스트하고, Seedance 2.0 rollback을 유지할 수 있습니다.

경로가 열렸다는 것만으로 워크로드가 프로덕션 준비가 되는 것은 아닙니다. 올바른 목표는 자체 입력에 대해 품질, 대기 시간, 과금, 실패 동작을 측정한 라이브 통합입니다.

2026년 8월 7일 검증 스냅샷: 공식 개발자 API와 EvoLink 경로가 출시되었습니다. EvoLink는 세 개의 workflow ID, 4~30초, 480p/720p, R2V 참조 분배를 제공합니다. 트래픽을 확대하기 전에 EvoLink에서 현재 가격과 계정 한도를 확인하십시오. Seedance25API는 사이트가 작성한 라이브 통합 보조 자료를 게시하며 ByteDance와 제휴 관계가 없습니다.

이 가이드가 다루는 것과 API 레퍼런스가 다루는 것

API 퀵스타트는 정확한 필드, 엔드포인트 예시, 현재 요청 스키마를 담당합니다. 이 가이드는 그 스키마를 둘러싼 엔지니어링 프로세스를 담당합니다.

질문	담당 페이지
오늘 사용할 수 있는 라이브 패턴은?	API 퀵스타트와 현재 EvoLink documentation
agent가 로드할 수 있는 요청/polling 구조는?	통합 스키마
타입이 있는 클라이언트를 어떻게 생성하나?	이 가이드
트래픽 확대 전에 어떻게 테스트하나?	이 가이드
스키마 변경은 어떻게 처리하나?	이 가이드
무엇이 2.0으로 폴백할 수 있나?	이 가이드와 2.5 vs 2.0 결정 가이드
최종 라이브 가격은?	가격 페이지와 provider 콘솔

이 책임을 분리해 두면 블로그가 문서의 낡은 사본이 되는 것을 막을 수 있습니다.

고정된 계획 계약에서 mock과 관측성을 거쳐 circuit breaker와 자격 있는 폴백까지 이어지는 Seedance 2.5 API 준비 워크플로

먼저 프로덕션 검증 경계를 정의하기

다음 문장을 프로젝트 README나 아키텍처 결정 기록에 적어 두십시오:

Before traffic: request validation, type generation, job lifecycle,
error mapping, fallback policy, logging, and callback idempotency.

Measure on the live route: output quality, latency, reference ingestion,
callback delivery, actual cost, failure behavior, and account rate limits.

이 경계는 수용 기준을 바꿉니다. CI는 유료 호출 없이 통과해야 하고, 그다음 작은 canary가 트래픽 확대 전에 라이브 전용 동작을 검증합니다.

1단계: 통합 스키마를 스냅샷하고 버전 관리하기

프로덕션 빌드마다 움직이는 원격 URL에서 클라이언트 코드를 생성하지 마십시오. 검토된 스냅샷을 다운로드하거나 vendor하고, 해시를 기록하고, 의도적으로 업데이트하십시오.

curl -fsSL https://seedance25api.io/openapi.json \
  -o contracts/seedance-2.5.openapi.json

shasum -a 256 contracts/seedance-2.5.openapi.json

통합 스키마는 다음을 모델링합니다:

라이브 POST /v1/videos/generations 태스크 생성;
GET /v1/tasks/{task_id}를 통한 polling;
workflow별 필수 model과 prompt;
문서화된 출시 필드와 참조 한도;
현재 EvoLink 태스크 상태 어휘: pending, processing, completed, failed;
로컬 회복력 테스트를 위한 대표적인 에러.

검증된 라이브 기준선: Seedance 2.5와 2.0 모두 POST /v1/videos/generations로 태스크를 생성하고 GET /v1/tasks/{task_id}로 조회합니다(Bearer 인증, /v1 prefix 필수). EvoLink provider documentation이 여전히 권위 있는 출처입니다. 이 독립 스키마를 고정해 두면 라이브 경로와 태스크 조회를 provider 어댑터 뒤에 두면서도 계약 변경을 리뷰할 수 있습니다.

2단계: 타입은 생성하되 도메인 타입은 독립적으로 유지하기

스냅샷에서 전송 타입을 생성합니다:

npx openapi-typescript@7 contracts/seedance-2.5.openapi.json \
  -o src/generated/seedance-transport.ts

생성된 타입이 애플리케이션의 도메인 모델이 되게 하지 마십시오. 생성된 전송 코드는 계약이 바뀌면 함께 바뀝니다. 리뷰 상태, 참조 역할, 승인된 출력 같은 제품 개념은 안정적인 애플리케이션 타입에 속합니다.

export type VideoRequest = {
  prompt: string;
  durationSeconds: number;
  quality?: string;
  references: Array<{
    type: "image" | "video" | "audio";
    url: string;
    role: string;
  }>;
};

export type VideoJob = {
  id: string;
  state: "queued" | "running" | "generated" | "failed";
  outputUrl?: string;
  errorCode?: string;
};

어댑터가 안정적인 도메인 타입을 현재 provider 전송 구조로 매핑합니다.

3단계: 경로 능력은 설정으로 유지하기

세 개의 라이브 EvoLink workflow ID(seedance-2.5-text-to-video, seedance-2.5-image-to-video, seedance-2.5-reference-to-video)를 사용하되, 선택된 ID를 UI 컴포넌트, 데이터베이스 레코드, 테스트, worker 코드 곳곳에 흩뿌리지 말고 configurable하게 유지하십시오.

type RouteConfig = {
  baseUrl: string;
  model: string;
  maxDuration?: number;
  qualities?: string[];
  maxImages?: number;
  maxVideos?: number;
  maxAudio?: number;
  enabled: boolean;
};

export const seedance25: RouteConfig = {
  baseUrl: process.env.EVOLINK_BASE_URL ?? "https://api.evolink.ai/v1",
  model: process.env.SEEDANCE_25_MODEL ?? "seedance-2.5-text-to-video",
  maxDuration: Number(process.env.SEEDANCE_25_MAX_DURATION ?? 30),
  qualities: (process.env.SEEDANCE_25_QUALITIES ?? "480p,720p").split(","),
  maxImages: 30,
  maxVideos: 10,
  maxAudio: 10,
  enabled: Boolean(process.env.EVOLINK_API_KEY),
};

이 경로는 사람이 EVOLINK_API_KEY를 제공할 때만 실행 가능해집니다. 자격 증명 없이 제출할 수 있는 코드가 있다면 시작 시 assertion을 추가하고, workflow별 필드를 검증하고, 트래픽 확대 전에 smoke test를 다시 실행하십시오.

4단계: provider가 요청을 보기 전에 검증하기

클라이언트 측 컨트롤은 사용성을 높이지만, 비용과 신뢰성을 보호하는 것은 서버 측 검증입니다.

export function validateRequest(input: VideoRequest, route: RouteConfig) {
  const errors: string[] = [];

  if (!input.prompt.trim()) errors.push("prompt is required");
  if (route.maxDuration && input.durationSeconds > route.maxDuration) {
    errors.push(`duration must be at most ${route.maxDuration}`);
  }
  if (input.quality && route.qualities && !route.qualities.includes(input.quality)) {
    errors.push(`quality ${input.quality} is not enabled for this route`);
  }

  const count = (type: VideoRequest["references"][number]["type"]) =>
    input.references.filter((r) => r.type === type).length;

  if (route.maxImages && count("image") > route.maxImages) errors.push("too many image references");
  if (route.maxVideos && count("video") > route.maxVideos) errors.push("too many video references");
  if (route.maxAudio && count("audio") > route.maxAudio) errors.push("too many audio references");

  return errors;
}

URL 접근 가능성, 미디어 메타데이터, 권한, signed URL 수명은 각각 별도의 검사가 필요합니다. 유효한 URL 문자열도 provider가 가져가기 전에 만료될 수 있습니다.

5단계: 전체 비동기 라이프사이클을 mock하기

유용한 mock은 상태를 가집니다. 즉시 완료된 영상을 반환하는 대신 작업 ID를 반환하고 상태를 순서대로 진행해야 합니다.

{
  "create": { "id": "mock-job-001", "status": "pending" },
  "poll_sequence": [
    { "id": "mock-job-001", "status": "pending", "progress": 0 },
    { "id": "mock-job-001", "status": "processing", "progress": 40 },
    {
      "id": "mock-job-001",
      "status": "completed",
      "progress": 100,
      "results": ["https://example.invalid/mock-output.mp4"]
    }
  ]
}

URL은 예약된 .invalid 도메인을 사용해, 테스트가 실수로 무관한 파일을 다운로드하지 않게 합니다.

의미 있는 모든 결과에 대해 fixture를 만드십시오:

Fixture	기대되는 애플리케이션 동작
`200 create`	polling 전에 provider 작업 ID를 영속화
`400 invalid request`	필드 수준 수정 안내 표시; 절대 그대로 재시도하지 않기
`401 invalid key`	중단하고 사람에게 키 설정 복구를 요청
`429 rate limited`	jitter가 있는 제한된 backoff 적용
시뮬레이션된 `503 unavailable`	경로 circuit을 열고 폴백 자격 평가
`completed`	출력, 사용량, 원본 응답 저장; 사람 리뷰로 진입
`failed`	사유 저장; 전송 성공으로 표시하지 않기
중복 콜백	상태 전이를 두 번 적용하지 않고 성공 반환

애플리케이션 마감 시간을 넘겨 processing에 머무는 작업도 시뮬레이션하십시오. provider 작업은 계속될 수 있지만, 사용자 대면 작업에는 명확한 타임아웃 상태와 확인을 재개할 방법이 필요합니다.

6단계: 어댑터를 스키마 테스트하고, 라이브 경로를 계약 테스트하기

첫 번째 스키마 테스트는 애플리케이션 요청이 고정된 통합 스키마에 수용되는지 증명해야 합니다. 두 번째는 모든 태스크 상태가 올바르게 매핑되는지 증명해야 합니다. 세 번째는 스키마가 예기치 않게 바뀌면 실패해야 합니다. 계약 차이에 대해서는 EvoLink provider documentation이 여전히 권위 있는 출처입니다.

import assert from "node:assert/strict";

const mapped = mapProviderJob({
  id: "mock-job-001",
  status: "processing",
  progress: 40,
});

assert.deepEqual(mapped, {
  id: "mock-job-001",
  state: "running",
  outputUrl: undefined,
  errorCode: undefined,
});

검토된 계약 스냅샷과 새로 가져온 사본을 비교하는 CI 단계를 추가하되, 자동으로 덮어쓰지는 마십시오:

curl -fsSL https://seedance25api.io/openapi.json \
  -o /tmp/seedance-2.5.latest.json

diff -u contracts/seedance-2.5.openapi.json \
  /tmp/seedance-2.5.latest.json

diff는 리뷰 트리거이지 파괴적 변경의 증거가 아닙니다. 설명 업데이트는 무해할 수 있지만, 필수 필드, enum, 상태, 응답 변경은 코드와 fixture 업데이트가 필요할 수 있습니다.

7단계: 실패 클래스별로 재시도 설계하기

“세 번 재시도”는 정책이 아닙니다. 실패 클래스마다 다른 대응이 필요합니다.

실패	재시도?	정책
응답 전 네트워크 타임아웃	경우에 따라	멱등성 보호와 함께 재시도하거나 재제출 전에 대사(reconcile)
`400`	아니요	요청 수정
`401`	아니요	secret 또는 권한 복구
`429`	예	provider 안내 준수; 지수 backoff와 jitter
시뮬레이션된 `503`	제한적	circuit을 열고 나중에 재시도하거나 자격 있는 폴백 사용
작업 `failed`	조건부	사유를 이해했고 정책이 허용할 때만 재시도
Poll 타임아웃	예	같은 작업의 polling을 재개; 중복 생성 금지

provider가 멱등성 키를 제공하지 않는다면 애플리케이션이 자체 제출 기록을 유지해야 합니다. provider가 요청을 수락한 뒤의 네트워크 타임아웃은 위험합니다. 무턱대고 재제출하면 과금되는 작업이 두 개 생길 수 있습니다.

8단계: 폴백 자격을 명시적으로 만들기

Seedance 2.0은 오늘도 주변 애플리케이션을 가동할 수 있지만, 폴백은 문자열 치환이 아닙니다. 2.5 기준으로 계획된 요청은 2.0의 길이나 참조 제약을 초과할 수 있습니다.

function canFallbackToSeedance20(input: VideoRequest) {
  return (
    input.durationSeconds <= 15 &&
    input.references.filter((r) => r.type === "image").length <= 9 &&
    input.references.filter((r) => r.type === "video").length <= 3 &&
    input.references.filter((r) => r.type === "audio").length <= 3
  );
}

위 한도는 인용된 공개 EvoLink 2.0 가이드를 반영한 것이며, 활성 경로와 여전히 대조 확인해야 합니다. 요청이 자격 미달이면 사용자에게 선택지를 주십시오: 길이 단축, 참조 제거, 나중에 2.5 경로 재시도, 또는 다른 검증된 경로 선택. 조용한 잘라내기(silent truncation)는 안전한 폴백이 아닙니다.

9단계: 트래픽 확대 전에 필요한 증거를 로깅하기

지금부터 구조화된 필드를 준비하십시오:

internal_request_id
provider_route
model_id
contract_version
provider_job_id
submit_attempt
http_status
provider_state
duration_requested
reference_counts
created_at / completed_at
usage_or_cost
output_url_expiry
review_outcome
fallback_route

Bearer 토큰을 로깅하지 말고, 민감한 signed URL은 마스킹 없이는 로깅하지 마십시오. 로그는 에러가 검증, 인증, 용량, 생성, 출력 조회, 사람의 거부 중 어디에서 왔는지 답할 수 있어야 합니다.

프로덕션 트래픽 전 검증 체크리스트

계약 테스트를 통과한 소프트웨어도 라이브 증거가 필요합니다. 다음 검사를 순서대로 실행하십시오:

provider documentation에서 최종 model ID와 계정 권한을 확인합니다.
계획 가정을 라이브 provider 스키마로 교체하고 모든 차이를 리뷰합니다.
짧고 리스크가 낮은 smoke 작업을 생성합니다.
반환되는 모든 상태와 출력 접근을 검증합니다.
성공 건의 과금 기록을 확인하고, 실패 건 과금은 별도로 조사합니다.
재시도 폭풍을 만들지 않고 rate limit과 일시 불가 처리를 테스트합니다.
콜백을 사용한다면 콜백 인증, 중복, 순서를 검증합니다.
고정된(frozen) 워크로드 평가 세트를 실행합니다.
자격이 있는 작업의 작은 canary만 활성화합니다.
kill switch가 트래픽을 검증된 경로로 되돌리는지 확인합니다.

애플리케이션 동작과 provider 동작이 일치할 때에만 통합은 canary를 시작할 준비가 된 것입니다. 출력 승인율, 비용, 지연, 에러 기준이 통과할 때에만 더 넓은 프로덕션으로 갈 준비가 된 것입니다.

출처

검증 노트: 2026년 8월 7일에 EvoLink의 Seedance 2.5, Seedance 2.0, 태스크 상세 documentation과 대조 확인했습니다. 로컬 OpenAPI 파일은 사이트가 작성한 통합 보조 자료이며, 현재 model ID, 요청 필드, 한도, 가격, 에러 계약에 대해서는 EvoLink 자체 documentation과 콘솔이 권위 있는 출처입니다.