API referenceMedia and accounts

Media and Image URLs

Presigned upload and download URLs for reference media and generated results. Uploads use a presigned POST with form fields and a server-enforced maximum file size. Media endpoints cover audio and video; the image endpoints add image-aware validation. Unlimited subscribers can also keep saved uploads to reuse across projects.

#Get a media upload URL

GET /v2/media/uploadUrl Auth required

Returns a presigned POST URL plus form fields for uploading a single media object up to maxSizeBytes. The form expires after one hour. Unknown query parameters return 400. Uploading an input for a jobId already claimed by another account returns 403.

#Query parameters

Name	Type	In	Description
typerequired	string	query	Asset type. Artist-side: `referenceAudio`, `referenceVideo`. Worker-side: `complete`, `preview`.
jobIdrequired	string	query	Job identifier the asset belongs to.
id	string	query	Artifact identifier. Required for worker uploads. For artist uploads, omit it, or use `referenceVideo1`–`referenceVideo3` or `referenceAudio1`–`referenceAudio3` to fill numbered reference slots; pass the same `id` when downloading.
contentType	string	query	Optional MIME type. Pinned so downloads sign the same S3 object key.

#Response

{
  "status": "success",
  "data": {
    "url": "https://<bucket>.s3-accelerate.amazonaws.com/",
    "fields": {
      "Content-Type": "video/mp4",
      "bucket": "<bucket>",
      "key": "video/2026-05-18/<jobId>/reference.mp4",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
      "X-Amz-Credential": "…",
      "X-Amz-Date": "…",
      "Policy": "<base64-encoded-policy>",
      "X-Amz-Signature": "<hex-signature>"
    },
    "maxSizeBytes": 104857600,
    "allowedContentTypes": [ "…" ]
  }
}

allowedContentTypes depends on the asset type:

Video uploads such as referenceVideo: video/mp4, video/quicktime, video/webm
Audio uploads such as referenceAudio: audio/mp4, audio/mpeg, audio/flac, audio/wav, audio/x-wav, audio/wave
Preview frames: image/jpeg, image/jpg, image/png, image/webp

How to upload. POST to the returned url (don't hard-code the host) as multipart/form-data, including every key and value from fields, then your file field last. The storage service returns 204 on success.

#Get a media download URL

GET /v2/media/downloadUrl Auth required

Returns a presigned download URL, valid for two days, for a previously uploaded asset or a completed job artifact. A deleted project's downloads return 404.

#Query parameters

Name	Type	In	Description
typerequired	string	query	Asset type. Same values as upload.
jobIdrequired	string	query	Job identifier.
id	string	query	Artifact id.
contentType	string	query	Optional MIME hint. The server uses the stored upload content type when available.
artifact	string	query	Optional. `lastFrame` returns the exported final frame of a Seedance 2.5 video that requested one; otherwise `404`.

#Response

{
  "status": "success",
  "data": { "downloadUrl": "https://<bucket>.s3-accelerate.amazonaws.com/…?X-Amz-…" }
}

#Get an image upload URL

GET /v2/image/uploadUrl Auth required

Returns a presigned POST URL plus form fields for image uploads (PNG, JPEG, WEBP, GIF). Same flow as media, with image-aware validation and content-type pinning.

#Query parameters

Name	Type	In	Description
typerequired	string	query	Asset type. Artist-side: `startingImage`, `cnImage`, `contextImage1`–`contextImage16`, `referenceImage`, `referenceImageEnd`, `referenceMask`. Worker-side: `complete`, `preview`.
jobIdrequired	string	query	Job identifier.
imageId	string	query	Artifact id. Required for worker uploads.
contentType	string	query	Optional MIME type, pinned for download.

#Response

{
  "status": "success",
  "data": {
    "url": "https://<bucket>.s3-accelerate.amazonaws.com/",
    "fields": {
      "Content-Type": "image/png",
      "bucket": "<bucket>",
      "key": "2026-05-18/<jobId>/startingImage.png",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
      "X-Amz-Credential": "…",
      "X-Amz-Date": "…",
      "Policy": "<base64-encoded-policy>",
      "X-Amz-Signature": "<hex-signature>"
    },
    "maxSizeBytes": 104857600,
    "allowedContentTypes": ["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]
  }
}

#Get an image download URL

GET /v2/image/downloadUrl Auth required

Returns a presigned download URL for an image artifact. Query parameters match the image upload endpoint.

#Response

{
  "status": "success",
  "data": {
    "downloadUrl": "https://<bucket>.s3-accelerate.amazonaws.com/…?X-Amz-…"
  }
}

Saved uploads. Unlimited subscribers can save an image, video, or audio file once and reuse it across projects without uploading it again. Saved uploads are private to the account. The JavaScript and Python SDKs use them automatically when you pass files to projects.create(), and expose projects.assets for explicit control; durable workflows take media_references URLs instead. Prepare, finalize, and bind require an active Unlimited plan (403 otherwise); listing, capabilities, and removal do not. Files are kept while the plan is active, and for 30 days after the later of the paid period's end and the last save or reuse.

#List saved uploads

GET /v1/assets Auth required

Returns data.assets, newest first, and data.limits (fileBytes, idleDays). Each record has id, name, bytes, contentType, state (uploading or ready), createdAt, and expiresAt (Unix milliseconds).

#Check saved-upload availability

GET /v1/assets/capabilities Auth required

Returns { enabled, limits }. enabled is false without an active plan or when saved storage is unavailable.

#Prepare a saved upload

POST /v1/assets/prepare Auth required

#Body

Name	Type	In	Description
sha256required	string	body	Lowercase hex SHA-256 of the file.
bytesrequired	integer	body	File size, from 1 to `limits.fileBytes`.
contentTyperequired	string	body	`image/png`, `image/jpeg`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`, `audio/mp4`, `audio/mpeg`, `audio/flac`, `audio/wav`, `audio/x-wav`, or `audio/wave`.
name	string	body	Optional label, up to 80 characters.

If the same file is already saved, returns its record with reused: true and nothing to upload. Otherwise returns the record with reused: false, an uploadUrl, and uploadHeaders. PUT the exact bytes to uploadUrl within five minutes, sending exactly those headers. An upload that is never finalized expires after one hour.

#Finalize a saved upload

POST /v1/assets/:id/finalize Auth required

Send a JSON body ({} is fine). Verifies size, type, and checksum, then returns the ready record. A mismatch returns 409, an expired upload 410, and a busy entry 423.

#Attach a saved upload to a project

POST /v1/assets/:id/bind Auth required

Copies a ready saved upload into a project input slot before you submit the project through the SDK. Body: { projectId, type, id? }. projectId is the UUID you will submit; type is an image input type from the image upload endpoint, referenceVideo, or referenceAudio, and must match the file's media type; id selects a numbered reference slot. Returns { assetId, projectId, type, contentType }. A project ID already claimed by another account returns 403.

#Remove a saved upload

DELETE /v1/assets/:id Auth required

Deletes the saved file; data is {}. Inputs already copied into existing projects are not affected. An unknown ID, or one owned by another account, returns 404.