Windpaint
Generation

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.

datafilerequired

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.

retention_daysinteger

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.

X-Windpaint-Projectstring

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.

Idempotency-Keystring

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.

FormatContent typeAsset kindLimits
PNG, JPEG, WebPimage/png, image/jpeg, image/webpimage20 MiB. Long edge at most 8192 px, short edge at least 64 px.
MP4, MOV, WebMvideo/mp4, video/quicktime, video/webmvideo200 MiB, 60 seconds.
MP3, WAV, M4A, OGGaudio/mpeg, audio/wav, audio/mp4, audio/oggaudio25 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.

StatusCodeCause
422input.invalidThe file is empty.
422input.unsupported_formatNot 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.
422input.too_largeOver the size limit for its kind. details has kind, size_bytes and max_bytes.
422input.dimensionsAn image outside the pixel limits. details has width, height, max_long_edge and min_short_edge.
422input.durationVideo or audio too long. details has kind, duration_s and max_duration_s.
422request.validation_failedretention_days is outside 1 to 365.
422idempotency.key_invalidIdempotency-Key is empty or over 255 characters.
409request.conflictThe project is archived.
409idempotency.key_reused / idempotency.in_progressThe Idempotency-Key was used with a different file, or the first upload with it is still running.
413request.bad_requestThe request body is over 201 MiB (the 200 MiB video limit plus room for multipart framing).
429rate_limit.requestsThe key’s requests per minute are spent.
408request.timeoutThe upload didn’t finish streaming within 300 seconds. Uses the timeout body, not the error envelope.