BytePlus Seedance 2.0 Video Generation

📖 Overview

Use BeeHears to call BytePlus Dreamina Seedance 2.0 video generation. This guide covers:

Async task API: POST /v1/video/generations to submit, GET /v1/video/generations/{task_id} to query
How to pass a reference image: top-level images: ["..."] array (public URLs)
Seedance 2.0 Fast model name, parameter limits and task query flow

⚠️ Current integration notes

Seedance 2.0 is an async task pipeline: submitting returns a task_id, then poll GET /v1/video/generations/{task_id} until the final result_url is ready. Reference images must use a publicly reachable URL (HTTPS preferred); private-network or internal-only URLs will fail to be fetched upstream and the request will silently degrade to text-only generation. The two main models are doubao-seedance-2-0 (Standard, supports 1080p) and doubao-seedance-2-0-fast (Fast, lower price, no 1080p); Mini, filter-off and Seedance 2.5 variants are listed in the model table below.

① Prerequisites

Terminal - Environment Variables

export BASE_URL="https://ai.beehears.com"
export TOKEN="sk-xxxxxxxxxxxxxxxx"

Common request headers:

Authorization: Bearer <TOKEN>
Content-Type: application/json

Your account needs permission to call BytePlus / VolcArk video models on the platform.

💡 Tip

If you already have a platform API token, you usually don't need to worry about the underlying channel, AK/SK, or plugin configuration. If the request returns feature_disabled, channel_not_available, or asset-library permission errors, contact the platform administrator.

② Models

The following models are publicly available:

Public Model	Upstream	Resolution	Notes
`doubao-seedance-2-0`	BytePlus Dreamina Seedance 2.0 (Standard)	480p / 720p / 1080p	Full-quality variant; supports 1080p output
`doubao-seedance-2-0-fast`	BytePlus Dreamina Seedance 2.0 Fast	480p / 720p	Lower price; does not support 1080p
`doubao-seedance-2-0-mini`	BytePlus Dreamina Seedance 2.0 Mini	Upstream default (not verified on this gateway)	Lightweight variant; same channel group and rate as Standard
`doubao-seedance-2-0-filter-off`	BytePlus Dreamina Seedance 2.0 (upstream content filter disabled)	Upstream default (not verified on this gateway)	You remain responsible for content compliance
`dreamina-seedance-2-5-ep`	BytePlus Dreamina Seedance 2.5	Upstream default (not verified on this gateway)	Newer generation; higher rate than 2.0. Uses the sd2 asset-group system
`dreamina-seedance-2-5-hc`	BytePlus Dreamina Seedance 2.5 (HC)	Upstream default (not verified on this gateway)	Uses the legacy `/v1/sd/assets` asset system, not interoperable with the sd2 asset groups used by the other variants

The model field in your request must use one of the exact names above. The following aliases do not exist on this gateway and will return model_not_found: seedance-2-0-260128, seedance-2-0-fast-260128. Other variants such as seedance-2-0, seedance-2-0-fast, dreamina-seedance-2-0-260128 and dreamina-seedance-2-0-fast-260128 do exist on the platform but belong to different channel groups — check your token's group access before using them. New models, if released, will be appended here.

③ Endpoints

Function	Method	Path
Create task	POST	`/v1/video/generations`
Query task	GET	`/v1/video/generations/{task_id}`

Submitting returns a task_id with status: queued immediately. Poll the query endpoint until status: SUCCESS to get the result_url (a signed MP4 direct link, valid for 24h; save it promptly).

⚠️ Deprecated paths (do not use)

Previous versions of this doc mentioned /v1/videos (OpenAI-style sync API) and /volcark/api/v3/contents/generations/tasks (VolcArk native path). Neither path is enabled on the current platform. The former returns HTTP 400 due to an input_reference field-type mismatch; the latter is swallowed by the SPA fallback router. Neither will create a task successfully.

④ Create Task Examples

4.1 Text to video

Terminal

curl -X POST "$BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "prompt": "A cinematic close-up of a glass greenhouse at sunrise, soft camera movement, natural light.",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9"
    }
  }'

Typical response:

{
  "id": "task_4ZzZhgCggCoiK2nZR93dhwleVAcopXZu",
  "task_id": "task_4ZzZhgCggCoiK2nZR93dhwleVAcopXZu",
  "object": "video",
  "model": "doubao-seedance-2-0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1778874483
}

Once you have the task_id, poll the query endpoint (see ⑥) until status becomes SUCCESS to obtain result_url.

4.2 Top-level fields

Only the following top-level fields are recognised by the adapter. Everything else must go inside metadata (see 4.3):

Field	Type	Required	Description
`model`	string	Yes	One of the names in the model table above — commonly `doubao-seedance-2-0` (Standard, supports 1080p) or `doubao-seedance-2-0-fast` (Fast, 480p/720p only)
`prompt`	string	Yes	Text prompt
`images`	string[]	No	Array of reference image URLs (publicly reachable, HTTPS preferred). The only effective reference-image field today.
`seconds`	string	No	Video duration in seconds. Must be a string, e.g. `"5"` / `"10"` / `"15"`. Range 4–15. Defaults to 5 if omitted.
`metadata`	object	No	All advanced parameters (resolution/ratio/generate_audio/etc.) go here. See 4.3.

⚠️ Duration: use top-level seconds (string) or duration (int)

Since the 2026-05-17 adapter upgrade, both top-level "seconds":"15" and "duration":15 are honoured; priority is seconds > duration > metadata.duration. If none is set, the upstream defaults to 5s.

✅ Recommended: "seconds": "15" or "duration": 15
✅ Also OK: "metadata": {"duration": 15}
❌ Invalid types (e.g. "duration": true / [15]) return HTTP 400

🚫 Top-level fields rejected with HTTP 400

Since 2026-05-17 the adapter performs strict validation: placing the following fields at the request-body top level returns HTTP 400 unsupported_top_level_field with a hint to move them into metadata. This replaces the previous silent-drop behaviour that caused "task succeeds but with the wrong settings" bugs.

resolution / ratio / generate_audio / watermark / size / seed / frames / camera_fixed / return_last_frame / callback_url / service_tier / draft — move them into metadata: {...}
content: [...] (OpenAI multimodal structure) — pass reference images via top-level images: ["..."] instead

About size: the upstream kapon OpenAI-style endpoint accepts "size":"1280x720" and derives resolution+ratio automatically. This gateway intentionally does not perform that derivation (to avoid ambiguous mappings like 854×480 vs 1280×720). Use explicit metadata.resolution + metadata.ratio instead.

ℹ️ Upstream capabilities not yet forwarded

references.audio[] / references.video[] (multimodal audio/video reference) — supported by the BytePlus Seedance 2.0 upstream but not yet wired through this gateway adapter. Contact the platform if you need them.
asset://<Asset_Id> (private asset library) — the adapter passes the URL through verbatim, but you still need the channel to have asset-library access enabled upstream. Try a real Asset_Id; if the upstream rejects it, contact the platform.

4.3 metadata advanced fields

All fields below live inside the request body's metadata object. The adapter unmarshals metadata directly into the upstream requestPayload, so field names mirror the upstream contract:

Field	Type	Description
`resolution`	string	`480p` / `720p` for both models, `1080p` only with `doubao-seedance-2-0` (Standard). Passing `1080p` with the Fast variant returns HTTP 400.
`ratio`	string	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive`. Recommended to leave empty so the upstream auto-fits the reference image.
`duration`	int	Alternate spelling for video length in seconds (4–15). Lower priority than top-level `seconds`.
`generate_audio`	bool	Whether to generate audio
`watermark`	bool	Whether to keep the watermark
`seed`	int	Fixed random seed for reproducible output
`frames`	int	Explicit frame count (mutually exclusive with `seconds`, subject to upstream version support)
`camera_fixed`	bool	Lock the camera to reduce shot movement
`return_last_frame`	bool	Also return the last frame as an image, useful for "continue from last frame" workflows
`callback_url`	string	Upstream task-completion webhook URL
`service_tier`	string	Upstream service tier (e.g. `default`); normal users do not need to set this

4.4 Image to video (with reference image)

Terminal

curl -X POST "$BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "prompt": "Use the reference image as the opening frame, slow camera push-in.",
    "images": [
      "https://example.com/my-reference-image.png"
    ],
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": false,
      "watermark": false
    }
  }'

The video uses the reference image as the opening frame and fits its aspect ratio. Pass metadata.ratio explicitly to override.

⑤ Reference Image Rules

Only public URLs are supported today, via the top-level images array:

{
  "images": [
    "https://example.com/my-image.png"
  ]
}

Constraints and tips:

The URL must be directly fetchable by the upstream from the public internet (HTTPS preferred). Private IPs, localhost, or internal-only addresses will fail and silently degrade to text-only generation.
If your image is hosted on a flaky origin, consider routing through a public image proxy such as https://wsrv.nl/?url=<origin-host>%2Fpath%2Ffile.png
Verify in an incognito window (no cookies) that the URL returns the image directly
asset://<Asset_Id> private asset URIs, video references, and audio references are not supported at this time

⑥ Query Task

Terminal

curl "$BASE_URL/v1/video/generations/task_4ZzZhgCggCoiK2nZR93dhwleVAcopXZu" \
  -H "Authorization: Bearer $TOKEN"

Typical response (success):

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_4ZzZhgCggCoiK2nZR93dhwleVAcopXZu",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://ark-acg-ap-southeast-1.tos-ap-southeast-1.volces.com/...mp4?X-Tos-...",
    "data": {
      "ratio": "3:4",
      "resolution": "720p",
      "duration": 5,
      "framespersecond": 24,
      "usage": { "total_tokens": 108900, "completion_tokens": 108900 }
    }
  }
}

State machine: NOT_START → IN_PROGRESS → SUCCESS / FAILURE. On failure, fail_reason explains why (e.g. content-safety reject). result_url is a signed temporary MP4 link, valid for 24 hours — re-host it to your own storage as soon as possible.

⑦ Billing

The platform derives billing SKUs from:

Requested model: doubao-seedance-2-0 (Standard) or doubao-seedance-2-0-fast (Fast)
Final resolution: 480p / 720p / 1080p (1080p only on Standard)
Whether a reference image is included

💰 Billing principles

You are only charged for successfully generated videos; creation failures, in-progress failures, and asset pre-processing failures do not incur the success fee. If upstream usage or creation-time billing metadata is missing while the task has succeeded, the platform falls back to a predefined high-tier SKU and leaves fallback/degraded markers and alerts internally to avoid silent under-billing or missed charges.

⑧ FAQ

8.1 Task SUCCESS but the video is unrelated to my reference image

Most common cause: wrong reference-image field. The current API recognises the top-level images: ["..."] array (recommended) and top-level input_reference: "..." (single URL, appended as a fallback since 2026-05-17). The singular image field and the OpenAI-style content: [{type:"image_url", ...}] structure are not consumed; content[] at the top level now returns HTTP 400. Switch to the example shown in ④4.4.

8.2 1080p rejected on Fast model

doubao-seedance-2-0-fast supports only 480p / 720p. For 1080p output, switch to doubao-seedance-2-0 (Standard).

8.3 Reference image URL is on a private / internal network

The upstream Dreamina service runs on the public internet and cannot reach your internal / private / localhost URLs. Re-host the image somewhere publicly fetchable (your own object storage, CDN, or a public image proxy) before putting it in the images array.

8.4 FAILURE with "sensitive information" in fail_reason

Triggered upstream content-safety review. Adjust the prompt or reference image and retry — no double billing.

🔗 Related Links

Back to docs home