Windpaint
Generation

Assets

Upload files, list and read assets, download their bytes, use them as inputs to generation jobs, and delete them.

An asset is a stored media file in a project: either something you uploaded or the output of a generation job. Jobs read their inputs from assets and write their outputs as assets, so the same id that comes back from one job can be passed to the next.

curl -X POST https://api.windpaint.ai/v1/generation/uploads \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -F "[email protected]"

Upload a file

POST /v1/generation/uploads takes a multipart form with the file in a field named data, and returns 201 with the new asset.

curl
curl -X POST https://api.windpaint.ai/v1/generation/uploads \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -H "X-Windpaint-Project: launch-video" \
  -F "[email protected];type=image/png"
FormatStored as kindLimits
PNG, JPEG, WebPimage20 MiB; long edge up to 8192 px, short edge at least 64 px
MP4, MOV, WebMvideo200 MiB; up to 60 seconds
MP3, WAV, M4A, OGGaudio25 MiB; up to 5 minutes
  • Type: detected from the file’s bytes. The filename extension and the part’s Content-Type are ignored. Other formats, including GIF, HEIC and AVIF, return 422 input.unsupported_format. See Inputs for every limit and error.
  • Cost: uploads are free. You only pay for generation and, past the first 7 days, storage.
  • Project: the asset goes into the project picked by the X-Windpaint-Project header, or your default project. Upload into the project you’ll run the job in, since inputs must come from the same project.
  • Retention: add ?retention_days=N to keep this file for fewer days than your organization’s setting. See Retention.
  • Retries: send an Idempotency-Key header and a retried upload returns the first asset instead of storing a second copy. See Idempotency.

You don’t always need to upload first: jobs also accept public https:// URLs and data: URIs as inputs and store them as assets for you. See Inputs.

The asset object

{
  "data": {
    "id": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b",
    "project_id": "5b0c7e1a-2f3d-4e5f-8a9b-0c1d2e3f4a5b",
    "job_id": null,
    "url": "https://api.windpaint.ai/v1/generation/assets/8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b/content",
    "kind": "image",
    "source": "upload",
    "content_type": "image/png",
    "size_bytes": 422193,
    "width": 1024,
    "height": 576,
    "duration_s": null,
    "filename": "frame.png",
    "source_url": null,
    "expires_at": "2026-10-11T14:01:02.551Z",
    "deleted_at": null,
    "deleted_reason": null,
    "created_at": "2026-10-04T14:01:02.551Z"
  }
}
idstring

The asset id. Use it in a job’s inputs and with the asset endpoints.

project_idstring

The project the asset belongs to.

job_idstring | null

For outputs, the request_id of the job that produced it. null for uploads.

urlstring

The asset’s API URL, .../assets/{id}/content. Fetching it needs your key. It also works in place of the id in inputs.

kindstring

image, mask, video, audio or text. Today you’ll see image, video and audio.

sourcestring

upload, output, url (fetched from an https:// input) or data_uri (decoded from a data: input).

source_urlstring | null

For url assets, the URL as you sent it. null otherwise.

content_typestring

MIME type.

size_bytesinteger

File size.

widthinteger | null

Pixel width for images and video.

heightinteger | null

Pixel height for images and video.

duration_snumber | null

Length in seconds for video and audio.

filenamestring | null

The uploaded filename. null for outputs.

expires_atstring | null

When the asset’s bytes will be deleted, from your organization’s retention setting. null means it’s kept until you delete it. Assets created before retention existed have null.

deleted_atstring | null

When the bytes were deleted. null while the asset is available.

deleted_reasonstring | null

expired or deleted, once the bytes are gone. null otherwise.

created_atstring

When the asset was stored (ISO 8601).

List and get assets

curl
# Assets in the current project, newest first
curl "https://api.windpaint.ai/v1/generation/assets?limit=50" \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"

# One asset
curl https://api.windpaint.ai/v1/generation/assets/8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"

GET /v1/generation/assets returns {"data": [Asset]} for the current project, uploads and outputs together, newest first. Assets past their expires_at or deleted are left out. limit takes 1 to 200 (default 50); there’s no cursor or offset and no filter by kind, so filter on kind or source client-side. GET /v1/generation/assets/{id} returns {"data": Asset}.

Read an asset’s bytes

GET /v1/generation/assets/{id}/content (the asset’s url) checks your key and answers with a 302 redirect to a signed download URL that’s valid for 15 minutes. Follow the redirect to get the file. Once an asset has expired or been deleted, /content and /url return 410 with code generation.asset_gone.

curl
curl -L https://api.windpaint.ai/v1/generation/assets/$ASSET_ID/content \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -o output.png

Don’t send your Authorization header to the redirect target. The signed URL carries its own credentials and will reject a request that adds yours. curl -L, Python requests and httpx drop the header automatically when a redirect goes to a different host; if you follow redirects by hand, make the second request without it.

Get a URL for a browser

A browser can’t send your API key, and you shouldn’t give it one. To show or download an asset in a web page, fetch the signed URL on your server and hand that to the browser:

curl https://api.windpaint.ai/v1/generation/assets/$ASSET_ID/url \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"
{ "data": { "url": "https://...signed...", "expires_in": 900 } }

The URL works without any header for expires_in seconds (15 minutes) and can go straight into an <img>, <video> or a download link. Fetch a new one when it expires; don’t store it. For anything longer-lived, download the bytes and serve them from your own storage. Media in your app has a full example.

Use assets as inputs

Pass assets to a job in inputs, keyed by slot name:

{
  "prompt": "slow dolly in",
  "inputs": { "start_frame": ["8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"] }
}

The rules:

  • References. Each value is an asset id, an asset URL returned by this API (https://api.windpaint.ai/v1/generation/assets/{id}/content), a public https:// URL, or a data: URI. URLs and data URIs are fetched at submit and stored as new assets in the job’s project. See Inputs.
  • Same project. The asset must be in the project the job runs in. An asset from another project, or an id that doesn’t exist, returns 422 with Input asset not found in this project. and the offending ids in details.asset_ids.
  • Right kind. Each slot accepts certain kinds (start_frame takes image). A wrong kind returns 422 naming the slot.
  • Right count. Each slot has a minimum and maximum; GET /v1/generation/capabilities lists them per model.
  • Not expired. An asset past its expires_at, or deleted, returns 422 with code generation.asset_gone.

Outputs are inputs too: any completed job’s outputs[].id can be passed to the next job in the same project. That’s how you go from an image to a video.

Reading across projects

Reads and use are scoped differently:

  • Reading (GET /assets/{id}, /content, /url) works for any asset in your organization, whatever project header you send, so an asset URL keeps working wherever it’s pasted inside your org.
  • Listing (GET /assets) shows only the current project.
  • Using as an input works only within the asset’s own project.

To use an asset from project A in a job in project B, download it and upload it into B.

Retention and deletion

Assets are kept for your organization’s retention period, 7 days by default, and then their bytes are deleted. Storage within the first 7 days is free. You can change the period from 1 to 365 days or keep assets forever, and storage past day 7 is billed. See Retention.

To delete an asset now:

curl -X DELETE https://api.windpaint.ai/v1/generation/assets/$ASSET_ID \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"

This returns 204 and removes the bytes right away. DELETE /v1/generation/requests/{request_id}/assets deletes a finished job’s outputs, and its inputs too unless you pass ?inputs=false. See Deleting assets.