EvoLink를 통한 Seedance 1.5 Pro API 연동 가이드: 비동기 작업, 콜백 및 모드 상세 분석

학습 내용

• EvoLink의 비동기 작업 API(생성 → 상태 확인 → 결과 수신)를 통한 Seedance 1.5 Pro 배포.
• callback_url의 안전한 사용(HTTPS 전용, 재시도 의미론 및 실패 시 처리).
• 하나의 엔드포인트로 텍스트-투-비디오, 이미지-투-비디오, 첫-끝 프레임 모드 사용법.
• 멱등성 키(Idempotency Key)와 재시도 예산을 통한 중복 처리 방지.
• 링크 만료(24시간 보관 창) 전 출력 자산의 재호스팅(Re-hosting) 방법.
• 불안정한 가격 정보에 의존하지 않는 "성공적인 출력당 비용" 모델 구축.
• Veo 3.1 및 Kling O1과의 통합 트레이드오프 비교(가격이 아닌 설계 구조 기반).

빠른 시작 체크리스트 (복사하여 작업 티켓에 붙여넣으세요)

• POST /v1/videos/generations를 구현하여 작업 생성
• GET /v1/tasks/{task_id} 폴링 구현
• callback_url 엔드포인트 구현 (2xx 즉시 응답 + 비동기 처리)
• 사용자 의도(예: "생성" 버튼 클릭)별로 멱등성 키 추가
• 24시간 이내에 비디오 자산 재호스팅
• 모니터링 수단: p50/p95 지연 시간, 정책 실패율, 재시도율, 성공당 시도 횟수

EvoLink API 계약 (구현 핵심)

• 작업 생성 → task_id 수신
• GET /v1/tasks/{task_id}를 폴링하거나 callback_url을 통해 콜백 수신
• 완료 시, results URL을 가져와서 즉시 다운로드(링크가 만료되기 때문)

엔드포인트 개요

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• 출력 링크는 24시간 동안 유효합니다. 신속하게 재호스팅하세요.

하나의 엔드포인트, 세 가지 모드 (image_urls를 통한 자동 감지)

• 이미지 0개 → 텍스트-투-비디오 (Text-to-Video)
• 이미지 1개 → 이미지-투-비디오 (Image-to-Video)
• 이미지 2개 → 첫-끝 프레임 (첫 프레임 + 끝 프레임 가이드를 사용한 생성)

• 요청당 최대 이미지 2개
• 각 이미지 크기 ≤ 10MB
• 지원 형식: jpg/jpeg/png/webp
• URL은 서버에서 직접 접근 가능해야 함

프로덕션 단계에서 중요한 요청 필드

다음은 실제 운영 시 활용하게 될 파라미터들입니다.

• model: "seedance-1.5-pro" 사용
• prompt (필수): 최대 2000 토큰
• duration: 기본 5초, 4~12초 지원

  운영 팁: 요금은 재생 시간에 비례하므로 재생 시간을 핵심 예산 제어 수단으로 활용하세요.

• quality: 480p 또는 720p (기본값 720p)
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (기본값 16:9)
• generate_audio: 불리언 (기본값 true)

  팁: 대화 내용을 큰따옴표로 묶으면 대사 전달력이 향상됩니다.

• callback_url: 완료/실패/취소된 작업을 위한 HTTPS 전용 콜백 URL (권장)

시나리오별 파라미터 제안 (빠른 의사결정용)

이 표는 문서나 기획서(PRD)에 인용하도록 설계되었습니다.

작업 수명 주기: 상태 머신 먼저 설계하기

안정적인 연동은 예측 가능한 내부 상태 머신(State Machine)에서 시작됩니다.

created → queued/processing → succeeded → (다운로드 → 재호스팅 → 전달)
                     └──────→ failed (정책 위반 | 일시적 오류 | 내부 오류)
                     └──────→ cancelled

최소 작동 예시 (EvoLink)

1) 작업 생성 (cURL) — 복사하여 즉시 실행 가능

이 예시는 쉘 이스케이프 문제를 피하기 위해 따옴표가 없는 간단한 프롬프트를 사용합니다.

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <사용자 토큰>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://your-domain.com/webhooks/evolink-task"
  }'

API는 즉시 다음과 같은 정보가 포함된 작업 객체를 반환합니다.

• id (작업 ID)
• status
• usage 필드(예: billing_rule, credits_reserved)

2) 작업 상태 폴링 (cURL)

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <사용자 토큰>'

완료 시 작업 객체에는 다음이 포함됩니다.

• 출력물 URL이 담긴 results 배열
• status 및 progress (진행률)

callback_url: 신뢰성 규칙 (생략 금지)

• HTTPS만 지원
• 내부/사설 네트워크 IP 차단
• 타임아웃: 10초
• 최대 3회 재시도 (재시도 간격: 1 / 2 / 4초)
• 콜백 바디 형식은 작업 조회 응답 형식과 동일

콜백 프로덕션 체크리스트

• 200ms–500ms 이내에 2xx 응답 (작업을 큐에 넣고 즉시 응답, 내부에서 무거운 작업 수행 금지)
• task_id가 존재하며 해당 테넌트/사용자의 것인지 확인
• 최종 상태를 기록하기 전 항상 GET /v1/tasks/{task_id}를 다시 조회
• 콜백 중복 처리 (결과가 이미 기록된 task_id는 무시)
• 디버깅을 위해 원시 콜백 페이로드 로그 기록 (민감 정보 제외)
• 콜백 실패율 증가 시 알림 설정 (보통 수신 측 엔드포인트 이슈임)

멱등성: 중복 처리(및 이중 결제) 방지

공급자 측의 처리가 정확하더라도 다음과 같은 이유로 시스템에서 중복이 발생할 수 있습니다.

• 사용자가 "생성" 버튼을 여러 번 클릭
• 모바일 네트워크의 재시도
• 게이트웨이 타임아웃

• 클라이언트가 사용자 의도당 하나의 idempotency_key 생성 (한 번의 클릭 = 하나의 키)
• 서버는 (user_id, idempotency_key) → task_id를 TTL과 함께 저장
• 동일한 키가 다시 들어오면 새 작업을 생성하지 않고 기존 task_id를 반환

API가 멱등성을 명시적으로 처리한다고 되어 있지 않다면, 애플리케이션 단계에서 직접 구현해야 합니다.

자산 전달: 24시간의 함정

출력 링크는 24시간 후에 만료되므로 여러분의 파이프라인에서 다음 작업을 수행해야 합니다.

• status=completed 시 결과를 즉시 다운로드
• 자체 오브젝트 스토리지(S3/GCS/R2)에 재호스팅
• CDN을 통한 서비스
• 메타데이터 영구 보관: task_id, 프롬프트 해시, 사용자 ID, 생성 설정, 모데레이션 결과 등

완료 시 자동으로 재호스팅하여 이를 방지하세요.

융통성 있는 비용 모델링 (고정 가격에 의존하지 않기)

가격 숫자가 아닌 지속 가능한 단위 경제학 모델이 필요합니다.

1) 플랫폼의 결제 기준 파악

운영 측면에서 비용을 결정하는 요인은 다음과 같습니다.

• duration (길수록 비쌈)
• generate_audio (오디오 추가 시 비용 발생)
• 반복 횟수 (사용자가 첫 시도에 만족하는 경우는 드묾)

2) "시도당 비용"이 아닌 "성공한 출력당 비용" 측정

다음을 추적하세요.

• attempts_per_success (시나리오별 성공당 시도 횟수)
• retry_rate (재시도율)
• policy_failure_rate (정책 위반 실패율)
• p95_latency (지연 시간 분포)

실제 단위 경제학:

세션당 성공적인 출력 수 × 성공에 필요한 평균 시도 횟수

3) 초안 → 승인 → 최종 생성 (가장 확실한 비용 절감 전략)

반복 시도가 많은 경우:

• 낮은 품질/짧은 길이의 저렴한 설정으로 초안 생성
• 사용자가 승인한 후 Seedance 1.5 Pro(오디오 포함)로 최종 결과물 생성

프로덕션에서의 함정과 해결책

1) 비동기 함정 (타임아웃 및 좀비 작업)

• "작업 TTL"과 "처리 중" UI 상태 설정
• p95 완료 시간을 추적하고 지연 발생 시 사용자에게 상황 안내

2) 모데레이션(검수) 결과 지연

"생성 후 검수 실패" 상태를 위한 UI/백엔드 설계를 준비하세요.

• 실패 원인 구분: 정책 위반 vs 일시적 오류 vs 내부 오류
• 정책 위반에 대해서는 절대 자동 재시도를 수행하지 않음
• 프롬프트 재작성 가이드 제공 (특히 민감한 내용 관련)

비교: Seedance 1.5 Pro vs Veo 3.1 vs Kling O1

가격 숫자는 변하지만 플랫폼의 설계 방식과 연동 편의성은 유지됩니다.

표 A — 연동 및 비용 산정 방식

표 B — 프로덕션 결정 매트릭스

의사결정 체크리스트 (빠른 결정용)

• 네이티브 오디오가 필요하고 프롬프트의 따옴표로 대사를 구조화할 수 있는 경우.
• 텍스트/이미지/첫-끝 프레임 모드를 하나의 계약으로 사용하고 싶은 경우.
• 24시간 이내에 자산 재호스팅을 자동화할 수 있는 경우.

• 재생 시간 기반의 예산 관리와 안정적인 클라우드 에코시스템 워크플로우를 선호하는 경우.

• 영상 편집/스타일 변경이 핵심이며 안정적인 접근 경로를 확보한 경우.

자주 묻는 질문 (FAQ)

Q: EvoLink에서 텍스트-투-비디오와 이미지-투-비디오를 어떻게 전환하나요?

Q: 콜백과 폴링 중 무엇이 더 안전한가요?

Q: 왜 결과를 재호스팅해야 하나요?

링크가 24시간 후에 만료되기 때문입니다. 완료 즉시 다운로드하여 보관하십시오.

Q: 중복 작업을 방지하려면 어떻게 해야 하나요?

지금 Seedance 1.5 Pro로 개발을 시작하세요

이제 API 사양과 장단점을 모두 파악하셨습니다. 지금 바로 여러분의 제품에 프로덕션 기능을 구현해 보세요.

• Seedance 1.5 Pro, Veo 3.1, Kling 등을 위한 단일 API 키.
• 재시도 정책이 정의된 비동기 작업 + 콜백.
• 투명한 크레딧 기반의 사용량 요금제.

대부분의 팀이 1시간 이내에 연동을 완료합니다.