Skip to main content
POST
Upload a custom asset for Seedance

Overview

Use this endpoint when your Seedance workflow needs a reviewed asset ID instead of a direct public URL. Typical cases:
  • Real-person photos
  • Realistic AI characters or avatars
  • Any material that needs to enter the asset review process before generation
Only assets whose Status is Active can be used in Seedance generation requests.

When Upload Is Required

Flow

  1. Prepare a publicly accessible resource URL.
  2. Call Seedance Asset Upload API with name, asset_type, and asset_url.
  3. For real-person assets, first complete Seedance Real-Person Asset Validation API, then pass the returned GroupId as group_id.
  4. If the upload succeeds, the API returns an asset_id.
  5. Asset requires review, wait until the review is approved before using it in generation. Call Seedance Asset Info API and keep polling until Status becomes Active.
  6. Use the approved asset identifier in Seedance video generation requests, typically in the form asset://xxx.

Request Example

For non-real-person assets, omit group_id. For real-person assets, group_id must be the GroupId returned by the validation result endpoint.

Response Example

Use Uploaded Assets In Seedance

After approval, pass the asset ID into the Seedance video generation endpoint:
  • img_urls
  • last_frame_image
  • reference_images
  • reference_videos
  • reference_audios

Asset Info

Query upload status and wait for the asset to become active

Real-Person Validation

Get the Asset Group ID required for real-person asset uploads

Seedance 2.0 Image to Video

Use uploaded image assets in image-to-video requests

Seedance 2.0 Reference to Video

Use uploaded image, video, and audio assets in reference-to-video requests

Authorizations

x-api-key
string
header
required

All APIs require authentication via API Key.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header:

x-api-key: YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
name
string
required

Display name of the asset.

Required string length: 1 - 64
Example:

"fashion-model-front"

asset_type
enum<string>
required

Type of asset being uploaded.

Available options:
Image,
Video,
Audio
Example:

"Image"

asset_url
string<uri>
required

Publicly accessible asset URL. Image, video, and audio uploads only support URL input; Base64 is not supported.

Input Requirements

General Rules

  • When passing image, video, or audio materials, only URLs are supported.
  • Base64 encoding is NOT supported.

Image Requirements

  • Formats: jpeg, png, webp, bmp, tiff, gif, heic, heif
  • Aspect Ratio (width / height): (0.4, 2.5)
  • Dimensions (px): (300, 6000)
  • File Size: less than 30 MB per image

Video Requirements

  • Formats: mp4, mov
  • Resolution: 480p, 720p
  • Duration: [2, 15] seconds
  • Dimensions:
    • Aspect Ratio (width / height): [0.4, 2.5]
    • Width/Height (px): [300, 6000]
    • Total Pixels: width × height ∈ [409600, 927408]
  • File Size: ≤ 50 MB per video
  • Frame Rate (FPS): [24, 60]

Audio Requirements

  • Formats: wav, mp3
  • Duration: [2, 15] seconds
  • File Size: ≤ 15 MB per audio
Example:

"https://example.com/assets/fashion-model-front.jpg"

group_id
string | null

Optional Asset Group ID for real-person asset uploads. Get this value from Seedance Real-Person Asset Validation API and pass it only when uploading assets that should be bound to that validated real person.

Example:

"group-20260331145705-*****"

Response

Upload request accepted

code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 422: Validation Error - The request parameters failed validation checks
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
  • 501: Generation Failed - Content generation task failed
  • 505: Feature Disabled - The requested feature is currently disabled
Available options:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
message
string

Response message, error description when failed

Example:

"success"

data
object