비디오 API

비디오 생성

Seedance 2.5, Seedance 2.5 CN, Seedance 2.0, Seedance 2.0 CN, Seedance 2.0 Fast, Seedance 2.0 Fast CN, Seedance 2.0 Mini, Seedance 2.0 Mini CN을(를) 실행하세요. 모든 비디오 요청은 폴링하거나 webhook으로 수신할 수 있는 작업을 생성합니다.

생성 모드

워크플로를 선택하려면 mode를 설정하세요. 기본값은 text_to_video입니다. 모드를 선택하면 아래 예시가 업데이트됩니다.

요청 예시

POSThttps://api.mlmux.com/v1/videos/generations

curl https://api.mlmux.com/v1/videos/generations \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "model/seedance-2.5-max",
  "prompt": "A cinematic tracking shot along a coastal road at sunrise, warm backlight, gentle camera drift",
  "mode": "text_to_video",
  "ratio": "16:9",
  "resolution": "720p",
  "duration": 8,
  "generate_audio": true,
  "route_mode": "official-cheap"
}'

매개변수

필드	타입	필수 여부	설명
`model`	string	예	아래 표에 명시된 모델 ID입니다.
`prompt`	string	예	장면, 피사체, 움직임, 카메라, 조명 및 사운드 연출입니다.
`mode`	string	아니요	`text_to_video`(기본값), `image_to_video`, `first_last_frame` 또는 `multi_ref`입니다.
`ratio`	string	아니요	지원 시 `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, `21:9` 또는 `adaptive`입니다. 기본값은 `adaptive`입니다.
`resolution`	string	아니요	해당 모델에 명시된 `480p`, `720p`, `1080p` 또는 `4K`입니다. 기본값은 `720p`입니다.
`duration`	integer	아니요	모델 허용 범위 내의 영상 길이(초 단위)입니다. 기본값은 5입니다. 모델이 직접 결정하도록 하려면 `-1`을 사용하세요.
`generate_audio`	boolean	아니요	영상과 동기화된 오디오를 생성합니다.
`route_mode`	string	아니요	`official` 또는 `official-cheap`입니다. 키의 기본 라우팅 모드를 따르며, 미설정 시 `official-cheap`이 기본값입니다.
`image_url`	string	조건부	`image_to_video`에 필수: 시작 프레임입니다.
`first_frame_url` `last_frame_url`	string	조건부	`first_last_frame`에 필수입니다. 대신 순서가 지정된 2개의 `image_urls`를 전달할 수도 있습니다.
`image_urls`	string[]	조건부	`multi_ref`용 참조 이미지입니다.
`video_urls` `audio_urls`	string[]	조건부	`multi_ref`용 참조 비디오 및 오디오입니다.

multi_ref는 최소 하나의 참조 파일이 필요합니다. Seedance 2.5는 이미지 최대 30개, 비디오 10개, 오디오 10개(총 50개)까지 허용되며, 다른 모델은 이미지 최대 9개, 비디오 3개, 오디오 3개(총 12개)까지 허용됩니다. 공개 https URL을 사용하거나, 먼저 POST /v1/uploads로 파일을 업로드하세요.

모델

모델	모델 ID	해상도	화면비	길이
Seedance 2.5	`model/seedance-2.5-max`	480p · 720p · 1080p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–30초
Seedance 2.5 CN	`model/seedance-2.5-cn-max`	480p · 720p · 1080p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–30초
Seedance 2.0	`model/seedance-2.0-max`	480p · 720p · 1080p · 4K	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 CN	`model/seedance-2.0-cn-max`	480p · 720p · 1080p · 4K	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Fast	`model/seedance-2.0-fast-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Fast CN	`model/seedance-2.0-fast-cn-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Mini	`model/seedance-2.0-mini-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Mini CN	`model/seedance-2.0-mini-cn-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초

이 ID들은 -max로 끝나므로 ratio, resolution, duration은 선택 사항이며 위의 기본값으로 대체됩니다.

작업 수명 주기

비디오 생성 요청 시 항상 작업 정보와 함께 HTTP 202가 반환됩니다. 해당 id를 저장하고 poll_url을 폴링하세요. status가 succeeded가 되면 응답에 video, usage 및 actual_charge_credits가 포함됩니다.

GEThttps://api.mlmux.com/v1/videos/generations/{task_id}

202 Accepted

{
  "id": "task_01a9...",
  "object": "video.generation.task",
  "status": "queued",
  "created": 1767225600,
  "model": "model/seedance-2.5-max",
  "api_method": "videos.generations.create",
  "poll_url": "/v1/videos/generations/task_01a9...",
  "progress": 0,
  "message": "queued",
  "estimated_charge_credits": 1.84
}

성공

{
  "id": "task_01a9...",
  "object": "video.generation.task",
  "status": "succeeded",
  "progress": 100,
  "message": "completed",
  "video": "https://.../generated/01a9....mp4",
  "last_frame_image": "https://.../generated/01a9....jpg",
  "usage": {
    "output_tokens": 172800,
    "video_seconds": 8,
    "video_resolution": "720p"
  },
  "estimated_charge_credits": 1.84,
  "actual_charge_credits": 1.79
}

실패한 작업은 status가 failed로 표시되며 message에 사유가 포함됩니다. 결과물 URL은 MLMux에서 호스팅되므로, 보관하려는 파일은 직접 다운로드하세요.

웹훅

폴링 대신 request.succeeded 및 request.failed 이벤트를 구독할 수 있습니다. 페이로드 및 서명 확인 방법은 웹훅 문서를 참조하세요.

비디오 API

비디오 생성

생성 모드

워크플로를 선택하려면 mode를 설정하세요. 기본값은 text_to_video입니다. 모드를 선택하면 아래 예시가 업데이트됩니다.

요청 예시

POSThttps://api.mlmux.com/v1/videos/generations

curl https://api.mlmux.com/v1/videos/generations \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "model/seedance-2.5-max",
  "prompt": "A cinematic tracking shot along a coastal road at sunrise, warm backlight, gentle camera drift",
  "mode": "text_to_video",
  "ratio": "16:9",
  "resolution": "720p",
  "duration": 8,
  "generate_audio": true,
  "route_mode": "official-cheap"
}'

매개변수

필드	타입	필수 여부	설명
`model`	string	예	아래 표에 명시된 모델 ID입니다.
`prompt`	string	예	장면, 피사체, 움직임, 카메라, 조명 및 사운드 연출입니다.
`mode`	string	아니요	`text_to_video`(기본값), `image_to_video`, `first_last_frame` 또는 `multi_ref`입니다.
`ratio`	string	아니요	지원 시 `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, `21:9` 또는 `adaptive`입니다. 기본값은 `adaptive`입니다.
`resolution`	string	아니요	해당 모델에 명시된 `480p`, `720p`, `1080p` 또는 `4K`입니다. 기본값은 `720p`입니다.
`duration`	integer	아니요	모델 허용 범위 내의 영상 길이(초 단위)입니다. 기본값은 5입니다. 모델이 직접 결정하도록 하려면 `-1`을 사용하세요.
`generate_audio`	boolean	아니요	영상과 동기화된 오디오를 생성합니다.
`route_mode`	string	아니요	`official` 또는 `official-cheap`입니다. 키의 기본 라우팅 모드를 따르며, 미설정 시 `official-cheap`이 기본값입니다.
`image_url`	string	조건부	`image_to_video`에 필수: 시작 프레임입니다.
`first_frame_url` `last_frame_url`	string	조건부	`first_last_frame`에 필수입니다. 대신 순서가 지정된 2개의 `image_urls`를 전달할 수도 있습니다.
`image_urls`	string[]	조건부	`multi_ref`용 참조 이미지입니다.
`video_urls` `audio_urls`	string[]	조건부	`multi_ref`용 참조 비디오 및 오디오입니다.

모델

모델	모델 ID	해상도	화면비	길이
Seedance 2.5	`model/seedance-2.5-max`	480p · 720p · 1080p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–30초
Seedance 2.5 CN	`model/seedance-2.5-cn-max`	480p · 720p · 1080p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–30초
Seedance 2.0	`model/seedance-2.0-max`	480p · 720p · 1080p · 4K	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 CN	`model/seedance-2.0-cn-max`	480p · 720p · 1080p · 4K	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Fast	`model/seedance-2.0-fast-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Fast CN	`model/seedance-2.0-fast-cn-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Mini	`model/seedance-2.0-mini-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초
Seedance 2.0 Mini CN	`model/seedance-2.0-mini-cn-max`	480p · 720p	adaptive · 16:9 · 21:9 · 4:3 · 1:1 · 3:4 · 9:16	4–15초

이 ID들은 -max로 끝나므로 ratio, resolution, duration은 선택 사항이며 위의 기본값으로 대체됩니다.

작업 수명 주기

GEThttps://api.mlmux.com/v1/videos/generations/{task_id}

202 Accepted

{
  "id": "task_01a9...",
  "object": "video.generation.task",
  "status": "queued",
  "created": 1767225600,
  "model": "model/seedance-2.5-max",
  "api_method": "videos.generations.create",
  "poll_url": "/v1/videos/generations/task_01a9...",
  "progress": 0,
  "message": "queued",
  "estimated_charge_credits": 1.84
}

성공

{
  "id": "task_01a9...",
  "object": "video.generation.task",
  "status": "succeeded",
  "progress": 100,
  "message": "completed",
  "video": "https://.../generated/01a9....mp4",
  "last_frame_image": "https://.../generated/01a9....jpg",
  "usage": {
    "output_tokens": 172800,
    "video_seconds": 8,
    "video_resolution": "720p"
  },
  "estimated_charge_credits": 1.84,
  "actual_charge_credits": 1.79
}

실패한 작업은 status가 failed로 표시되며 message에 사유가 포함됩니다. 결과물 URL은 MLMux에서 호스팅되므로, 보관하려는 파일은 직접 다운로드하세요.

웹훅

폴링 대신 request.succeeded 및 request.failed 이벤트를 구독할 수 있습니다. 페이로드 및 서명 확인 방법은 웹훅 문서를 참조하세요.