Uploads
Upload an image, video or audio file as an asset you can pass to a generation job.
POST /v1/generation/uploads
Stores a file as an asset in the current project and returns it. Use the asset’s id (or url) in a job’s inputs, for example as the start_frame of a wan-2.2-i2v clip. Uploads are free.
Scope: generation:write
Body
Send multipart/form-data with a single file part. Any part name works; data and file are both common.
The file. Its format is detected from its bytes; the part’s Content-Type and the filename’s extension are ignored. The filename is kept as the asset’s filename.
Keep this file for 1 to 365 days, then delete it. It can only shorten your organization’s retention setting; a larger value is reduced to it. It must be a query parameter (?retention_days=3); a multipart field with that name is ignored.
The project to upload into, by id or slug. Defaults to the API key’s default project, then your organization’s default project. A multipart body has no project_id field, so the header is the only way to pick a project here.
1 to 255 characters. A retry with the same key and the same file within 24 hours returns the first asset instead of storing a second copy. See Idempotency.
Accepted formats and limits. The same rules apply to URL and data URI inputs on submit; see Input requirements.
| Format | Content type | Asset kind | Limits |
|---|---|---|---|
| PNG, JPEG, WebP | image/png, image/jpeg, image/webp | image | 20 MiB. Long edge at most 8192 px, short edge at least 64 px. |
| MP4, MOV, WebM | video/mp4, video/quicktime, video/webm | video | 200 MiB, 60 seconds. |
| MP3, WAV, M4A, OGG | audio/mpeg, audio/wav, audio/mp4, audio/ogg | audio | 25 MiB, 5 minutes. |
GIF, HEIC, HEIF and AVIF images are rejected. An MP4 that holds only audio is stored as audio/mp4 under the audio limits. The asset’s width, height and duration_s are read from the file where they apply.
Uploads count toward your key’s requests per minute, not toward submits. See Rate limits.
Response
201 Created with {"data": Asset}. See the Asset object for every field. Uploaded assets have source: "upload", job_id: null and source_url: null. expires_at follows your retention setting or retention_days.
Errors
Errors use the standard error envelope.
| Status | Code | Cause |
|---|---|---|
422 | input.invalid | The file is empty. |
422 | input.unsupported_format | Not one of the formats above, or a file that can’t be read as its detected kind. details has detected (for example GIF or HEIC/HEIF/AVIF, or null) and allowed. |
422 | input.too_large | Over the size limit for its kind. details has kind, size_bytes and max_bytes. |
422 | input.dimensions | An image outside the pixel limits. details has width, height, max_long_edge and min_short_edge. |
422 | input.duration | Video or audio too long. details has kind, duration_s and max_duration_s. |
422 | request.validation_failed | retention_days is outside 1 to 365. |
422 | idempotency.key_invalid | Idempotency-Key is empty or over 255 characters. |
409 | request.conflict | The project is archived. |
409 | idempotency.key_reused / idempotency.in_progress | The Idempotency-Key was used with a different file, or the first upload with it is still running. |
413 | request.bad_request | The request body is over 201 MiB (the 200 MiB video limit plus room for multipart framing). |
429 | rate_limit.requests | The key’s requests per minute are spent. |
408 | request.timeout | The upload didn’t finish streaming within 300 seconds. Uses the timeout body, not the error envelope. |