메인 콘텐츠로 건너뛰기
POST
Main changes vs 2.0: max duration 15s → 30s; references 9 images + 3 videos + 3 audios → 30 images + 10 videos + 10 audios; audio-only reference supported; mov output added.
Note: resolution supports 480p / 720p / 1080p (2.0’s 4k is not available on 2.5).

Authentication

string
필수
Bearer token auth. Get a key from the API Key page.

Request parameters

string
필수
Fixed value: seedance-2.5
boolean
기본값:"false"
비디오 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.
  • true: omni-moderation-latest로 프롬프트와 입력 이미지를 검토
  • false 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)
검토 대상:
  • 텍스트: prompt, negative_prompt
  • 이미지: image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • 이미지 유형 비공개 asset:// 소재: 원본 공개 URL을 조회한 후 검토
  • Base64 이미지: 공개 URL로 변환한 후 검토
video_urls, audio_urls 및 비디오/오디오 유형 비공개 소재는 검토 모델이 비디오와 오디오를 지원하지 않으므로 검토되지 않습니다.지원 모델 ID: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0(이전 이름), seedance-2.5.검토 호출 자체는 비디오 요청을 제출한 사용자에게 청구되지 않습니다.
  • 콘텐츠가 감지되면 HTTP 400(nsfw_content_detected)이 동기식으로 반환됩니다. 작업과 task_id가 생성되지 않으며 비디오 생성 할당량도 차감되지 않습니다
  • 검토 서비스를 사용할 수 없거나 시간 초과 또는 잘못된 응답이 발생하면 fail-open으로 처리되어 생성 요청이 계속됩니다. 이 옵션을 절대적인 콘텐츠 안전 보장으로 사용하지 마세요
  • 공개 이미지 URL로 확인할 수 없는 입력은 건너뜁니다. 지원하지 않는 모델에서는 nsfw_check: true가 알림 없이 무시됩니다
사용 예시:
감지 시 응답:
boolean
true로 설정하면 480p 초안을 생성합니다. seedance-2.5만 지원하며 생략하면 일반 생성으로 처리합니다.
  • resolution은 480p만 허용하며 생략 시에도 480p
  • draft_task_id와 함께 사용 불가
  • 초안은 생성 시점부터 3일간 유효하며 성공 후 1080p 최종 영상 생성에 사용 가능
전체 과정은 초안 모드를 참조하세요.
string
완료된 초안으로 1080p 최종 영상을 생성합니다. 영상 URL이 아닌 초안 제출 응답의 APIMart 작업 ID(data[0].task_id)를 입력합니다.
  • seedance-2.5만 지원하며 초안과 같은 모델을 사용
  • 현재 API Key의 사용자 소유이고 성공적으로 완료되었으며 생성 후 3일 이내인 초안이어야 함
  • resolution은 1080p만 허용하며 생략 시에도 1080p
  • draft: true와 함께 사용 불가. prompt, 참조 자료, 길이 등 상속 필드를 다시 전송하지 마세요
변경 가능한 필드와 제한은 초안 모드를 참조하세요.
string
일반 생성 및 초안 생성 시 필수입니다. draft_task_id로 최종 영상을 생성할 때는 전달하면 안 되며 초안 프롬프트를 자동 상속합니다.Prompt. Reference media with @图片1 / @视频1 / @音频1 (1-based index matching array order). English aliases in prompts may also be used depending on model behavior; keep indices aligned with arrays.Example: "Use @视频1 for first-person framing throughout, @音频1 as BGM, first frame is @图片1"
string
기본값:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.초안 모드 예외: draft: true는 480p만 지원하고 기본값도 480p입니다. draft_task_id는 1080p만 지원하고 기본값도 1080p입니다.
string
기본값:"adaptive"
Aspect ratio (field name aspect_ratio is also accepted).Values: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (default)
Edit, extend, and first/last-frame jobs have hard size constraints — see Task types and constraints.
integer
기본값:"5"
Duration in seconds:
  • 4 ~ 30
  • -1: model picks duration (pre-charge at the 30s cap; settle to actual length after completion)
If omitted: generate and bill 5 seconds.
boolean
기본값:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
기본값:"false"
Add an “AI generated” watermark. Default false.
integer
Random seed. Different seeds usually yield different results for the same request; the same seed is similar but not guaranteed identical.
string
기본값:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
기본값:"auto"
Sub-task type hint: auto / reference / edit / extend.Passing reference / edit / extend validates that type’s constraints at submit time. Invalid requests return 400, create no task, and charge nothing. See Task types and constraints.
array<string>
Reference image URLs, all treated as reference_image.Supports:
  • Public URL: https://example.com/pic.jpg
  • Private asset: asset://cm9xxxxxxxx
For first/last frames use image_with_roles.
  • Max 30 images
  • Prefer image_with_roles for first/last-frame roles
array<object>
Images with explicit roles.Example:
If video_urls / audio_urls are present, first_frame / last_frame are auto-converted to reference_image (multimodal reference job).
array<string>
Reference videos (reference_video).Input: video URL or asset ID (asset://...).See Reference video specs.
array<string>
Reference audio URLs (reference_audio). Public URLs or asset://....Max 10; total duration ≤ 30s (each clip 2~30s).
2.5 supports audio-only reference (no image/video required).
boolean
기본값:"false"
When true, the successful result also includes the last-frame image for chaining.
array<object>
Tool list for enhancements such as web search.Example:

Media limits

Reference video specs

  • Input: video URL or asset ID (asset://...)
  • Container: mp4, mov — codecs in the table below
  • Resolution: 480p, 720p, 1080p
  • Duration: each clip [2, 30] s; up to 10 reference videos; total duration of all videos ≤ 30s
  • Per-video dimensions:
    • Aspect ratio (width/height): [0.4, 2.5]
    • Side length (px): [300, 6000]
    • Total pixels: [640×640=409600, 3326×2494=8295044], i.e. width × height must fall in [409600, 8295044]
  • Size: each video ≤ 200 MB
  • Frame rate (FPS): [24, 60]

Supported codecs

Task types and constraints

The service infers task type from references and prompt intent. The last three types hard-constrain size / duration; violations fail asynchronously after the job starts (e.g. InvalidParameter.TaskTypeConstraint):

Turn async errors into sync errors with omni_reference_task_type

Passing reference / edit / extend declares the sub-task type so its constraints are validated at submit time. Invalid requests return 400 immediately: no task is created and nothing is charged — you do not have to poll until failed. Notes:
  • If edit omits duration, the platform sets it to -1. Omitting duration otherwise defaults to 5 seconds, which conflicts with the upstream edit requirement of -1. The trade-off is a 30-second prepaid hold (same as duration: -1); unused amount is refunded after completion. For a smaller hold, skip edit and use default auto.
  • If edit sends duration explicitly, it must be -1. Any other value returns 400 (output length follows the source video).
  • ⚠️ You can still fail asynchronously with InvalidParameter.TaskTypeMismatch. Upstream re-classifies the job from the prompt; a mismatch with your declared type is rejected. Keep prompt wording aligned (edit: “edit / delete / replace…”; extend: “extend forward/backward / continue…”).
  • All Seedance 2.5 channels share the same validation and upstream payload; switching channels does not change this behavior.

Asset library

You can pass public URLs as references, or upload into the library first and use asset://. Prefer the library when:
  1. Real human faces must use the library — raw URLs are blocked by content moderation; only approved library assets can be used
  2. Assets are reused often — upload once, skip repeated moderation on later jobs, faster submits
  3. URLs are signed temporary links — the platform stores a durable copy on ingest so later use does not depend on the original URL staying alive
  4. Library assets are synced to all available channels so multi-channel routing can use them wherever the job lands
The library is shared with the 2.0 family; approved asset:// IDs work in both 2.0 and 2.5 generation requests. Full submit fields: also see Private avatar assets.

Upload assets

The response includes a local task id. Poll with Get task status (GET /v1/tasks/{id}). After approval, list assets to obtain the asset:// ID.

Media limits (validated at submit)

Violations return 400 immediately (which asset index and which rule), without starting moderation or consuming moderation quota: Error example:
For 30s video assets, submit with "model": "seedance-2.5" (2.0 cannot use assets longer than 15s).
If the platform cannot probe the media (e.g. network blip), it may pass through and leave the decision to moderation.

Use in generation requests

Reference approved assets with asset:// in image_urls / image_with_roles / video_urls / audio_urls:
Multi-channel: after ingest, assets sync to all available channels so any routed channel can use them. If a channel’s copy is missing, the platform may re-upload from the original URL as a fallback (if that URL is already expired, that channel is skipped and another takes over).

Management APIs (quick reference)

Asset APIs are free of charge (auth + rate limits only); they do not create billing records.

FAQ

Q: How long does moderation take?
Images usually seconds; video and real-person assets may take minutes. Poll the task id until a terminal status.
Q: Moderation failed with no clear reason?
Some failures omit a detailed reason (often a transient fetch failure). The platform already retries once; if it still fails, change the URL (ensure it is publicly downloadable) and resubmit.
Q: Same asset for both 2.0 and 2.5 — upload twice?
No. Upload once; asset:// works for both generations. Cross-channel / cross-model sync is handled by the platform.
Q: Can I pass a real-person face as a raw URL?
Real-person assets must go through the library first.

Billing

아래 규칙은 일반 생성과 초안에 적용합니다. 초안 기반 최종 영상은 초안 모드 과금을 참조하세요.
  • Billed by seconds × resolution tier.
  • With reference video input: billable seconds = total input video duration (≤30s) + output duration, at the input-reference rate tier.
  • duration = -1 (auto): pre-charge at the 30s cap; settle to actual output after completion.
  • Omit duration: generate and bill 5 seconds.
  • Failed jobs or content moderation blocks: full refund (charge only on successful output).

초안 모드

480p 초안을 생성해 화면을 확인한 뒤 해당 작업 ID로 1080p 최종 영상을 생성합니다. 최종 영상은 초안의 프롬프트, 참조 자료, 길이, 화면 비율, seed, 오디오 설정 및 작업 유형을 재사용하여 초안의 화면과 맞춥니다.

1단계: 480p 초안 생성

일반 생성 요청에 "draft": true를 추가합니다. 자료 및 작업 유형 제한은 동일합니다. resolution 생략 시 480p이며 720p 또는 1080p를 보내면 400을 반환합니다.
data[0].task_id에서 초안 ID를 읽고 작업 상태를 폴링하세요. data.status가 completed가 된 후에만 최종 영상을 제출합니다.
5~15초마다 조회를 권장합니다. pending은 대기, processing은 생성 중, completed는 성공, failed는 실패입니다. 영상 주소는 data.result.videos[].url 배열의 url[0]에서 읽습니다.

2단계: 1080p 최종 영상 생성

1단계에서 받은 ID를 draft_task_id에 입력합니다. resolution 생략 시 1080p이며 다른 해상도는 400을 반환합니다.
최종 영상은 새 작업 ID를 반환합니다. GET /v1/tasks/{task_id}로 결과를 조회하세요. 다음 필드는 초안에서 상속합니다. 같은 값이어도 다시 전송하면 400을 반환하므로 보내지 마세요. prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools. 다음 출력 옵션을 변경할 수 있습니다.
draft: true와 draft_task_id는 함께 사용할 수 없습니다. 초안과 최종 영상 모두 service_tier를 지원하지 않습니다.초안 유효기간은 생성부터 3일입니다. 작업이 없거나 다른 사용자 소유, 미성공, 초안이 아님 또는 만료된 경우 최종 영상 제출 시 400을 반환하고 작업 생성 및 과금은 하지 않습니다.
최종 영상은 초안을 생성한 동일 경로를 사용하며 시스템이 자동 연결합니다. 해당 경로가 일시적으로 사용 불가하면 제출 시 400을 반환합니다. 나중에 같은 draft_task_id로 재시도하세요. 만료되지 않은 초안으로 최종 영상을 여러 번 생성할 수 있습니다. 각 생성은 독립 작업이며 별도 과금됩니다.

초안 모드 과금

초안은 일반 480p 영상으로 과금합니다. 참조 영상 입력 길이는 기존대로 포함하며 합계 최대 30초입니다. 최종 영상은 1080p로 과금합니다. 1단계에 원본 참조 영상이 포함되었으면 1080P-input 등급, 없으면 일반 1080P 등급을 선택하며, 해당 등급의 토큰 단가로 정산합니다. 최종 영상의 과금 대상 입력 시간은 1단계 원본 참조 영상의 총 길이이며 최대 30초입니다. 생성된 Draft 영상 자체는 영상 입력으로 계산하지 않습니다. 최종 영상 POST는 계속 draft_task_id를 참조하며, 참조 자료나 다른 상속 필드를 다시 보내면 안 됩니다. 자료를 다시 보내지 않아도 원본 참조 영상 길이는 과금 계산에 포함됩니다. 예를 들어 1단계에서 원본 참조 영상 22초와 출력 11초를 요청했다면, 최종 영상 토큰은 11 + 22 = 33초와 1080P-input 등급의 토큰 단가로 추정합니다. 성공 후 실제 토큰 사용량으로 정산하여 초과분을 환불하거나 부족분을 추가 청구합니다. 실패 시 전액 환불하며 단가와 할인은 모델 요금을 따릅니다.
너비와 높이는 해당 작업의 출력 픽셀 크기입니다. 성공 후 data.usage.completion_tokens에서 정산 토큰 수를 확인할 수 있습니다.

Request examples

Text-to-video (30s)

Multimodal reference (image + video + audio)

Video edit

First–last frame

Private asset

Common errors

Response (submit)

integer
Status code; 200 on success
array
Submit response with status / task_id

Completed task (GET /v1/tasks/{task_id})

After submit, poll with Get task status. When status is completed, the payload looks like this.

Completed response example

Completed fields

Notes

  • Failed tasks (status=failed): cost is always 0 (pre-charge fully refunded); reason in data.error.message
  • usage may be missing for a few seconds after completion (settlement lag); query again shortly

Differences from 2.0