Seedance 2.0 — Volcano / Ark Native Entry

Besides the OpenAI-compatible /v1/video/generations path, Seedance 2.0 also exposes Volcano Ark / BytePlus-native entry points so clients already written against Ark docs or the BytePlus SDK can integrate with zero protocol changes.

This entry only reshapes request/response format. The upstream channel, billing, groups, and routing are identical to /v1/video/generations.

Equivalent paths

The three prefixes below behave identically; pick any one:

Operation	Method	/api/v3 (official Ark path)	/v3 (common shorthand)	/ark/api/v3
Create video task	POST	/api/v3/contents/generations/tasks	/v3/contents/generations/tasks	/ark/api/v3/contents/generations/tasks
Query task status	GET	/api/v3/contents/generations/tasks/{task_id}	/v3/contents/generations/tasks/{task_id}	/ark/api/v3/contents/generations/tasks/{task_id}
Upload asset	POST	/api/v3/sd/assets	/v3/sd/assets	/ark/api/v3/sd/assets
Query asset	GET	/api/v3/sd/assets/{asset_id}	/v3/sd/assets/{asset_id}	/ark/api/v3/sd/assets/{asset_id}

About /v3

Partner questionnaires often write /v3/contents/generations/tasks (dropping /api). This platform mounts both /v3 and /api/v3. Unmatched /v3/* paths return an API 404 JSON, not the SPA HTML page.

Authentication

Authorization: Bearer YOUR_EZMODEL_API_KEY
Content-Type: application/json

Use an EZModel token; it is shared with /v1/video/generations.

Base URL

https://www.ezmodel.cloud
# or
https://api.ezmodel.cloud

Example: POST https://www.ezmodel.cloud/v3/contents/generations/tasks

Create video — request body

Follows the Ark content-generations-tasks schema:

Field	Type	Required	Description
model	string	Yes	Model name, e.g. dreamina-seedance-2-0-hc
content	array	Yes	Content items (see below)
duration	integer	No	Duration in seconds
resolution	string	No	480p / 720p / 1080p / 4k (Fast/Mini: 480p/720p only)
ratio	string	No	Aspect ratio. Supports adaptive, 16:9, 9:16, 1:1, and other model-supported values. For image-to-video, adaptive follows the reference image's aspect ratio
generate_audio	boolean	No	Whether to generate audio
watermark	boolean	No	Whether to add a watermark
return_last_frame	boolean	No	Return the last frame for continuation
execution_expires_after	integer	No	Task execution timeout in seconds
callback_url	string	No	Completion callback URL

content[] item types:

type	Fields	Description
text	text	Prompt text (multiple items are joined with newlines)
image_url	image_url.url + role	Reference image, first frame, or last frame (HTTP(S) or asset://)
video_url	video_url.url + role	Reference video
audio_url	audio_url.url + role	Reference audio for speech, singing, or lip sync

Roles: reference_image, first_frame, last_frame, reference_video, and reference_audio.

Real Person / Avatar with Reference Audio

Upload the person image first, then use an HC model with the returned asset:// reference:

{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "Keep the identity and sing the reference audio naturally"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20260726161146-sh9fq"}, "role": "reference_image"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/vocal.mp3"}, "role": "reference_audio"}
  ],
  "duration": 5,
  "resolution": "480p",
  "ratio": "9:16",
  "generate_audio": true
}

First/Last Frame and Continuation

{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "Transition smoothly from day to night"},
    {"type": "image_url", "image_url": {"url": "https://example.com/day.jpg"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://example.com/night.jpg"}, "role": "last_frame"}
  ],
  "duration": 4,
  "resolution": "720p",
  "return_last_frame": true,
  "execution_expires_after": 3600,
  "callback_url": "https://example.com/callbacks/seedance"
}

return_last_frame is forwarded to the generation service. When the upstream returns a final frame, the completed task response includes a top-level last_frame_url; it can be reused as first_frame in a continuation request.

Reference Video and Video Modification

There is no separate edit endpoint. Submit the source video as reference_video in a new task:

{
  "model": "dreamina-seedance-2-0-hc",
  "content": [
    {"type": "text", "text": "Keep the person and motion; change the background to a rainy night street"},
    {"type": "video_url", "video_url": {"url": "https://example.com/source.mp4"}, "role": "reference_video"}
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

The video can also be uploaded with AssetType: "Video" and referenced through asset://.

Text-to-video example

curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "A cinematic shot of a glass perfume bottle on a marble table, slow camera push in"}
    ],
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9"
  }'

Response (Ark shape):

{
  "id": "mvt-512d4ffd9ce54256",
  "status": "queued"
}

Asset library (private avatar / real-person)

Virtual-avatar and real-person assets share one asset API. AssetType is the media type (Image / Video / Audio), not a person category. Use any *-hc model (-hc / -fast-hc / -mini-hc) when generating with real-person / avatar references.

EZModel uses the SD direct-upload flow and does not require an Asset Group. The historical /v1/asset-groups + /v1/assets flow is retired. Doubao's /v1/doubao-sd-1/assets flow is not exposed. GroupId may be null.

Upload

curl https://www.ezmodel.cloud/v3/sd/assets \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/avatar_front.jpg",
    "Name": "avatar_front",
    "AssetType": "Image"
  }'

Query

curl https://www.ezmodel.cloud/v3/sd/assets/asset-20260726161146-sh9fq \
  -H "Authorization: Bearer $YOUR_API_KEY"

Assets are isolated by account. Accessing another account's asset returns 404 asset not found.

Generate with an asset (hc)

curl https://www.ezmodel.cloud/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-hc",
    "content": [
      {"type": "text", "text": "The man in a black suit looks confidently at the camera and nods"},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260726161146-sh9fq"}}
    ],
    "duration": 5,
    "resolution": "480p",
    "ratio": "9:16"
  }'

Query task status

curl https://www.ezmodel.cloud/v3/contents/generations/tasks/mvt-512d4ffd9ce54256 \
  -H "Authorization: Bearer $YOUR_API_KEY"

On success, content.video_url is usually a platform CDN direct link (no auth). The response shape matches Ark; only the URL host differs. If CDN transfer fails, the gateway falls back to an authenticated proxy URL. Upstream origin URLs are never exposed.

Query-field compatibility

Seedance tasks are executed through the Service Inference Video channel. The supplier accepts generation options on create but may omit them from its query response. To preserve the Ark / V3 contract, the gateway stores the confirmed, forwarded fields in private task data: model, duration, resolution, ratio, generate_audio, watermark, return_last_frame, and execution_expires_after.

Query responses use the upstream value first and the submitted snapshot only as a fallback; boolean false values are preserved. Fields without either a supplier value or a submitted value, such as a supplier-generated seed, are not guessed. Snapshots apply to tasks created after this compatibility update; historical tasks continue to expose the upstream fields already stored for them.

For i9star integrations, the execution chain is: client -> i9star /v1/video/generations -> EZModel V3 -> Service Inference Video -> origin execution. The outer i9star task id can differ from the inner EZModel task id, so retain both when troubleshooting.

Status mapping: queued / processing / succeeded / failed.

Only single-task lookup is exposed; GET /v1/video/tasks listing is not. callback_url is forwarded to the generation service. Use a public HTTPS endpoint that responds 2xx quickly and handles retries idempotently, then query the task once to confirm the final video URL and usage.

Relation to the OpenAI-compatible entry

Both entries share the same token, channel, and billing. task_id values are interchangeable across entries (mind path and response shape differences). Asset paths /v1/sd/assets and /v3/sd/assets (plus /api/v3/sd, /ark/api/v3/sd) are equivalent.

Notes

• Prefer dreamina-seedance-2-0-* model names. Map official Volcano / BytePlus model ids via channel model redirects if needed.
• Real-person / avatar images and asset:// references require any *-hc model.
• Base supports 4k; Fast / Mini support 480p / 720p only.
• Fast models support only 480p and 720p.
• HTTP(S) and asset:// image, video, or audio references select with_ref; text-only tasks select no_ref. See the Seedance 2.0 main doc.
• Asset upload itself is free.
• All *-ep models are retired and must not be configured or requested.