Skip to content
Reading settings
Developer support

Storage ​

A storage repository saves model-generated files to your own cloud storage. Specify a repository ID when creating a task, and the platform transfers the artifacts after generation succeeds. Task queries return the file access URLs.

This guide uses Seedance video tasks as an example. Transfers include the generated video and a last-frame image when requested and returned. Check each model's API documentation for custom storage support.

Before you start ​

  1. Prepare a cloud storage bucket, access credentials, and a file access URL.
  2. Open Storage in the platform console, create a repository configuration, and pass the connectivity check.
  3. Copy the repository ID (UUID). The repository must belong to the API key's user and be available.

Cloud storage credentials are different from the API key used for model requests. Do not use a bucket name or cloud storage access key as the repository ID.

Request instructions ​

Add the OSS parameters to the task creation request headers, not the JSON request body. Both oss-id and oss-path are optional.

  • oss-id: The storage repository UUID. Provide it to use custom storage; omit it to use platform default storage. Use it only when custom storage is enabled for the service.
  • oss-path: A directory prefix such as file/images. This header has no effect without oss-id.

Creating a repository configuration in the console does not automatically change task storage. Include oss-id in each creation request that should use custom storage.

Request headers example ​

json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_KEY",
  "oss-id": "YOUR_STORAGE_UUID",
  "oss-path": "file/images"
}

This JSON illustrates header names and values; it is not a request body. Replace YOUR_API_KEY, YOUR_STORAGE_UUID, and file/images with your API key, repository UUID, and directory prefix.

The Seedance creation request headers look like this:

http
POST /api/v3/contents/generations/tasks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
oss-id: YOUR_STORAGE_UUID
oss-path: file/images

Authorization and Content-Type are required for task creation. See Create a video task for model parameters and Authentication for authentication details.

Storage path rules ​

  • oss-path supports up to 128 characters: English letters, digits, underscores, hyphens, dots, and /.
  • Leading and trailing whitespace and / are removed. .., standalone dot segments, consecutive /, Chinese characters, spaces, and other special characters are not allowed.
  • Valid examples: file/images, videos/2026-11, output_v1.
  • Invalid examples: ../videos, projects//demo, ./videos.

This parameter is a directory prefix, not a filename or a complete URL. The platform appends the resource type, date, and filename.

Omitting the header or leaving it empty adds no custom directory prefix. Files are still organized by resource type and date; they are not necessarily saved directly in the bucket root. Use the final URL returned by the task query.

Get transfer results ​

Save the task id returned after acceptance and query it with the same API key used for creation. Queries do not need oss-id or oss-path; the storage destination is determined at creation.

Model generation and file transfer have separate progress states. status=succeeded means model generation succeeded, but files may still be transferring. Also check:

  • custom_storage_status: PENDING, PROCESSING, SUCCESS, or FAILED for pending, processing, successful, or failed transfers.
  • content.video_url: The video access URL when ready.
  • content.last_frame_url: The last-frame image access URL when requested and ready.
  • can_retry_transfer: Whether any failed artifact can still be retried. true does not mean a retry has started.
  • transfer_source_expired: Whether any failed artifact's source has expired or cannot be downloaded.
  • transfer_error_message: The transfer failure description.

Continue querying until the URLs you need are available, then download the files. Do not send the platform API key to file URLs when downloading artifacts.

See Query a video task for queries and complete response details.

Frequently asked questions ​

What if the repository is invalid or parameters are rejected? ​

  • InvalidStorageRepo: Check the UUID, ownership, and whether the repository is deleted or unavailable.
  • CustomStorageDisabled: Custom storage is not enabled for the service. Contact platform support.
  • InvalidParameter: Check the UUID format of oss-id and the length and character rules of oss-path.

What if generation succeeds but transfer fails? ​

Read transfer_error_message and check cloud credentials, permissions, the bucket, and network configuration. If can_retry_transfer=true, retry the original task through the platform's transfer retry feature or contact support.

A transfer retry only saves existing artifacts again; it does not invoke the model again. An artifact cannot be transferred after its source becomes unavailable. For tasks with multiple artifacts, can_retry_transfer and transfer_source_expired may both be true, meaning only some failed artifacts remain retryable. Do not create another generation task solely because a transfer failed, as this may incur new generation charges.

Do repository changes or deletion affect existing tasks? ​

Tasks use the configuration version bound at creation. New tasks use the updated version, while accepted tasks and their transfer retries continue using the original version. Keep the old configuration usable for tasks still in progress.

Deleting a repository prevents new tasks from selecting it, but does not delete existing cloud artifacts. Accepted tasks may still transfer using the original configuration. Manage cloud files in your cloud storage service.

Private links are valid for the configured 1 to 7 days from issuance. Repeated task queries do not refresh links or extend their validity.

An expired link does not mean the file was deleted. Retrieve the file or issue a new link through your own cloud storage tools. Preserve the complete URL and signature parameters; do not replace the domain or modify the path.