Seedance image library

Prepare each image separately, then use its asset://<id> in a normal POST /v1/videos request. Use the library when it is enabled for your account and model. The returned id identifies the registered material; you do not need an additional file_id.

For the library, use seedance-2.0 or seedance-2.5 when this capability is enabled for your account and key. Access to video generation alone does not imply access to the library.

BASE_URL is your HTTPS origin without /v1. Use BASE_URL, API_KEY and the same model throughout. Upload from your server; never expose the API key in an end user's browser.

Create a group

Save the group for subsequent uploads. Use purpose: "ordinary" for ordinary materials. Creating a group does not verify a person's identity or grant permission to use their image.

curl --fail-with-body "$BASE_URL/v1/seedance/asset-groups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reference-group-001" \
  -d '{"model":"seedance-2.5","purpose":"ordinary","name":"References"}'

A confirmed creation returns HTTP 201:

{
  "object": "seedance.asset_group",
  "id": "group_ID",
  "operation_id": "op_ID",
  "status": "created"
}

Use one Idempotency-Key of 8–128 characters for one group with unchanged parameters. Repeating it returns the existing result; changing parameters with the same key returns HTTP 409.

Upload each image separately

curl --fail-with-body "$BASE_URL/v1/seedance/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'model=seedance-2.5' \
  -F 'group_id=group_ID' \
  -F 'file=@reference.png'

Each request contains one valid JPEG/PNG, at most 10 MiB and 36 megapixels. A corrupt file or exceeded limit returns HTTP 400 with a reason. Review determines whether the image can be used with the selected model.

Upload and approval are separate stages. The response reports this file's state:

{
  "object": "seedance.asset",
  "id": "asset_ID",
  "operation_id": "op_ID",
  "status": "Processing",
  "ready": false
}

The API provides neither an exact progress percentage nor a guaranteed review time. Show the state of each file separately. Enable video creation after all selected references are ready.

Check status and save the ID

curl --fail-with-body \
  "$BASE_URL/v1/seedance/assets/asset_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

In this API, model is also required for status reads and deletion. Use the model with which you created the group and material.

A ready image has status: "Active", ready: true and uri: "asset://asset_ID". Poll with a pause, for example three seconds, and increase it after HTTP 429/503. A temporary status error is not a rejection.

If the ID is not yet confirmed, save operation_id and poll the operation:

curl --fail-with-body \
  "$BASE_URL/v1/seedance/asset-operations/op_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

For submission_unknown, do not create a replacement or invent an ID from the filename. Repeating the same upload does not register the material again. If requires_support: true, send operation_id to support.

Create video with ready materials

curl --fail-with-body "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.5",
    "prompt":"The object from the reference rotates smoothly.",
    "seconds":"4",
    "size":"1280x720",
    "input_reference":"asset://asset_ID"
  }'

For multiple images, use image_urls: ["asset://asset_ID"]. For explicit roles, use image_with_roles: [{"url":"asset://asset_ID","role":"reference_image"}]. Image order and roles are preserved. Unready, deleted, inaccessible or incompatible materials are rejected. Only image assets are supported here; audio/video assets and asset links in multipart generation requests are not.

Save the video id and poll the normal GET /v1/videos/{id}. Repeating video creation may create another task; do not retry automatically after a timeout. Reference approval does not guarantee approval of every future video: the prompt and generated content must also comply with the rules.

Reuse and deletion

Save IDs in your library and use them in subsequent videos. Identical bytes in the same group, account and model are not registered twice, including concurrent uploads. Changing the file, group or model creates a different context; do not assume compatibility across models.

The library is scoped to the account, group, model and connection. Different keys can access the same material only when these conditions match. If your application serves multiple users, your server must track ownership of groups and materials and enforce each user's access.

curl --fail-with-body -X DELETE \
  "$BASE_URL/v1/seedance/assets/asset_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

After deleted: true, the material cannot be reused through the API. This does not delete previously generated videos or confirm erasure of every copy of the original file. Uploading the same deleted material to the same group does not restore it; use a new group only if another registration is necessary and permitted.

HTTP 403 means no access, 404 an absent or inaccessible material, 409 an unready material or key conflict, 429 a temporary limit, and 503 an unavailable status check. For support, provide the model, time, HTTP status and operation_id/id; never send API keys or secret URLs.