동영상 생성 API

동영상 생성 API는 비동기 동영상 작업을 생성합니다. 생성 요청은 작업 ID와 함께 HTTP 202를 반환합니다. 해당 ID로 작업 상태가 succeeded 또는 failed가 될 때까지 조회한 다음, 완성된 MP4를 다운로드하세요.

아래 예시는 https://api.icodeeasy.cc를 기본 URL로 사용합니다. 아래에 설명된 모든 엔드포인트 호출에는 API 키가 필요하며, 성공 후 반환되는 서명된 결과 파일 URL만 예외입니다.

Authorization: Bearer <API 키>

엔드포인트

5분 빠른 시작

1. 작업 생성

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <API 키>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.5",
    "prompt": "비 내리는 미래 도시 거리, 카메라가 천천히 전진하고 젖은 도로에 네온이 반사된다",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

생성 요청은 HTTP 202를 반환합니다.

{
  "id": "vid_1785398400000000000",
  "task_id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "queued",
  "model": "doubao-seedance-2.5",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:00Z"
}

작업 ID로는 task_id 사용을 권장합니다. 조회, 다운로드, 삭제에 사용할 수 있으며 id는 호환 기간 동안 같은 값으로 유지됩니다. 202 응답은 작업이 접수되었다는 뜻이며, 동영상이 이미 완성되었다는 뜻은 아닙니다.

2. 작업 조회

생성 응답의 task_id를 TASK_ID에 넣으세요.

TASK_ID='vid_1785398400000000000'
curl "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}" \
  -H 'Authorization: Bearer <API 키>'

약 5초마다 한 번씩 조회하세요. 현재 작업이 queued 또는 running 상태인 동안에는 다른 작업을 생성하지 마세요.

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "running",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:20Z",
  "progress": 42
}

progress는 참고용이며 없을 수도 있습니다. 진행률이 아닌 status를 기준으로 판단하세요.

3. 동영상 다운로드

status가 succeeded가 되면 응답에 url과 최종 cost_rmb가 포함됩니다.

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:01:18Z",
  "progress": 100,
  "url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "cost_rmb": 0.528
}

표준 인증 콘텐츠 경로를 통해 다운로드하고 리디렉션을 따르세요.

TASK_ID='vid_1785398400000000000'
curl -L "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}/content" \
  -H 'Authorization: Bearer <API 키>' \
  -o result.mp4

콘텐츠 경로는 HTTP Range와 일반적인 조건부 다운로드 헤더를 지원합니다. 성공하기 전에 콘텐츠를 요청하면 409 video_not_ready가 반환됩니다.

작업 수명 주기와 안전한 재시도

재시도 규칙:

• HTTP 202를 받은 뒤에는 반환된 task_id를 계속 조회하세요. 생성 요청을 반복하면 다른 작업이 생성될 수 있습니다.
• 작업 조회와 다운로드 GET 요청은 안전하게 재시도할 수 있습니다.
• 생성 요청에서 submission_unknown이 반환되면 다른 요청을 제출하지 마세요. 작업이 이미 접수되었을 수 있으므로 요청 시간, 모델, 프롬프트 요약과 함께 지원팀에 문의하세요.
• 작업이 최종 failed 상태로 확인된 후에는 다른 동영상을 생성하려는 경우에만 새 작업을 만드세요.

웹훅과 callback_url은 지원하지 않습니다. 대신 작업 엔드포인트를 조회하세요.

생성 요청 참고 자료

모든 텍스트 지시문은 prompt에 넣으세요. content는 참조 이미지와 동영상에만 사용합니다.

참조 미디어 목록(content)

content는 첫 프레임과 마지막 프레임, 여러 개의 순서 없는 참조 이미지, 또는 Motion Control용 이미지 한 개와 동영상 한 개처럼 작업 하나에 여러 미디어를 담기 위한 목록입니다. 각 항목의 image_url 또는 video_url에 HTTPS URL 문자열을 직접 입력합니다.

[
  { "type": "image_url", "image_url": "https://cdn.example.com/first.png", "role": "first_frame" },
  { "type": "image_url", "image_url": "https://cdn.example.com/last.png", "role": "last_frame" }
]

• 이미지 타입: image_url 또는 input_image.
• 동영상 타입: video_url 또는 input_video.
• 프레임 역할: first_frame과 last_frame. 마지막 프레임을 사용하려면 항상 첫 프레임이 필요합니다.
• Motion 역할: reference_image 한 개와 reference_video 한 개.
• Grok 참조 이미지에는 역할을 지정하지 않습니다. reference_image도 허용됩니다.
• 참조 오디오는 현재 지원하지 않습니다.
• 미디어는 작업이 읽는 동안 유효한 공개 HTTPS URL이어야 합니다.
• 이미지는 image_url, 동영상은 video_url에 넣습니다.

첫 프레임 + 마지막 프레임 전체 호출 예시

두 이미지를 공개 HTTPS URL에 배치한 뒤 URL을 content에 직접 넣습니다.

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <API 키>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "첫 프레임에서 마지막 프레임까지 카메라가 부드럽게 이동한다",
    "content": [
      {"type":"image_url","image_url":"https://cdn.example.com/first.png","role":"first_frame"},
      {"type":"image_url","image_url":"https://cdn.example.com/last.png","role":"last_frame"}
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

첫 프레임만 전달할 수는 있습니다. 같은 요청에 첫 프레임이 없으면 마지막 프레임만 전달할 수 없습니다.

모델 사용 예제

Seedance: 텍스트, 첫 프레임, 마지막 프레임

Seedance 2.5, Seedance 2.0 Standard, Fast, Mini와 Seedance 1.5 Pro는 텍스트 기반 동영상 생성과 첫/마지막 프레임 기반 생성을 지원합니다. 참조 이미지에는 프레임 역할을 명시해야 하며, Seedance 2.5가 이 계열의 첫 번째 모델입니다.

{
  "model": "doubao-seedance-2.5",
  "prompt": "아침 햇빛이 변하는 동안 카메라가 유리 조각 주위를 돈다",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-last.png", "role": "last_frame" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5의 기본값은 480p, 9:16, 4초, 생성 오디오 활성화입니다. 첫 프레임 또는 첫/마지막 프레임을 사용하면 화면 비율은 adaptive로 정규화됩니다.

MiniMax H3: 텍스트, 첫 프레임, 마지막 프레임

MiniMax-H3는 동일한 공개 요청으로 텍스트 기반 동영상 생성과 첫/마지막 프레임 생성을 지원합니다. 768P 또는 2K, 4–15초, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 화면 비율을 사용할 수 있습니다. 기본값은 768P, 9:16, 5초입니다. generate_audio를 보내지 마세요. H3의 공개 계약에는 생성 오디오 요청 토글이 없습니다.

Kling: 프레임 기반 생성

{
  "model": "kling-v3",
  "prompt": "옅은 안개를 뚫고 기차가 역으로 들어온다",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-last.png", "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

Kling의 주요 차이점:

• kling-v2-6: 마지막 프레임에는 1080p가 필요합니다. 생성 오디오는 1080p에서만 사용할 수 있으며 마지막 프레임과 함께 사용할 수 없습니다.
• kling-3.0-turbo: 첫 프레임만 지원하며 생성 오디오는 지원하지 않습니다.
• kling-v3와 kling-v3-omni: 첫/마지막 프레임과 생성 오디오를 지원합니다.
• kling-v3-omni는 역할이 없는 참조 이미지도 최대 두 개까지 허용하지만, 한 요청에서 역할 없는 이미지와 프레임 역할 이미지를 섞지 마세요.
• kling-video-o1: 첫/마지막 프레임을 지원하며 생성 오디오는 지원하지 않습니다.

Grok: 순서 없는 참조 이미지

Grok은 참조 이미지 URL을 최대 일곱 개까지 허용합니다. first_frame 또는 last_frame 역할을 지정하지 마세요.

{
  "model": "grok-imagine-1.5-video",
  "prompt": "카메라가 상승하는 동안 협곡 위로 구름이 흐른다",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/grok-reference.png" }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 6
}

Grok의 기본값은 480p, 9:16, 6초입니다. 생성 오디오는 지원하지 않습니다.

Kling Motion Control

공개 HTTPS 이미지 한 개와 3~30초 길이의 공개 HTTPS MP4 동영상 한 개를 지정하세요.

{
  "model": "kling-v3-motion-control",
  "prompt": "캐릭터의 정체성을 유지하고 참조 동작을 따른다",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/character.png", "role": "reference_image" },
    { "type": "video_url", "video_url": "https://cdn.example.com/motion.mp4", "role": "reference_video" }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}

• character_orientation: "image": 참조 동영상은 3~10초여야 합니다.
• character_orientation: "video": 참조 동영상은 3~30초여야 합니다.
• Motion Control 모델에는 resolution, ratio, duration, generate_audio를 보내지 마세요.

모델 기능 표

표준 모델에서 생략한 선택 항목은 위에 표시된 각 모델의 기본값을 사용합니다. model 자체는 항상 필수입니다. 서비스는 작업을 시작하기 전에 조합의 유효성을 검사합니다.

응답 및 다운로드 동작

모든 작업 응답은 다음 형식을 사용합니다.

반환된 URL 형식을 가정해 저장하지 말고 GET /v1/videos/tasks/{id}/content를 사용하세요. HTTP 클라이언트에서 -L을 사용하거나 리디렉션을 활성화하세요. 인증된 콘텐츠 엔드포인트는 200, 206 Partial Content 또는 릴레이 관리 스토리지로의 리디렉션을 반환할 수 있습니다.

서명된 릴레이 파일 URL은 API 키 없이 열 수 있으며, 전체 URL을 소유한 사람은 해당 동영상에 접근할 수 있습니다. 공개 로그, 페이지 또는 클라이언트 측 분석에 노출하지 마세요.

안전하게 종료된 작업을 삭제하면 HTTP 204가 반환되며 릴레이가 관리하는 동영상 파일도 함께 삭제될 수 있습니다. 필요한 결과는 작업을 삭제하기 전에 다운로드해 저장하세요. 작업이 실행 중이거나 요금 정산이 완료되지 않은 경우 삭제 요청은 409 video_delete_unsafe로 거부됩니다. 로컬 작업 기록을 삭제해도 이미 시작된 동영상 생성은 취소되지 않습니다.

오류 처리

HTTP 오류는 다음 형식을 사용합니다.

{
  "error": {
    "type": "invalid_request",
    "message": "model is not supported"
  }
}

실패한 작업 응답은 다음과 같을 수 있습니다.

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

요금 청구

동영상 생성에는 월간 할당량이 아닌 계정 잔액을 사용합니다.

작업 가격 = 선택한 모델/규격의 표시 RMB 초당 가격 × 청구 시간(초)

가격 페이지에서 현재 초당 가격을 확인하세요. 해상도, 생성 오디오 또는 Motion Control 모드에 따라 다른 표시 초당 가격 항목이 선택될 수 있습니다. 표준 모델의 청구 시간은 요청한 duration이며, Motion Control의 청구 시간은 감지된 참조 동영상 길이를 정수 초로 올림한 값입니다.

작업을 생성할 때 계정 잔액으로 비용을 충당할 수 있어야 합니다. 잔액이 부족하면 생성을 시작하기 전에 402가 반환됩니다. 성공한 작업의 cost_rmb가 최종 요금의 기준입니다. 명확히 실패한 작업에는 요금이 부과되지 않습니다.