Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

​
What you’ll do

Upload a video or large image directly to Runflow’s storage and reference the resulting asset by ID in subsequent run requests.

​
When to use this

POST /v1/asset-uploads accepts size_bytes up to 50 MiB (52,428,800 bytes); larger uploads are rejected at create time.
Input sizeApproach
< 1 MiBInline base64 or a public URL is fine.
1 MiB to 50 MiBInline if convenient, presigned upload if you control the server.
> 50 MiBNot supported by the asset-upload API. Host the file at a public URL and pass that URL on the run.

​
Prerequisites

  • A Runflow API key.
  • The file on disk or in memory.

​
Steps

1

Create an upload

Get a presigned URL. Tell Runflow the filename, MIME type, and exact byte size.
curl -X POST https://api.runflow.io/v1/asset-uploads \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "perfume-bottle.webp",
    "mime_type": "image/webp",
    "size_bytes": 2400000
  }'
Response (201 Created):
{
  "asset_id": "01J0...",
  "upload_url": "https://storage.runflow.io/..."
}
2

PUT the file to upload_url

Use the URL exactly as returned. No auth header, the presigned URL carries the credentials.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/webp" \
  --upload-file ./perfume-bottle.webp
3

Confirm the upload

Tell Runflow the upload is complete. The body is optional; pass folder_id to file the asset under a folder.
curl -X POST https://api.runflow.io/v1/asset-uploads/{asset_upload_id}/confirmations \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response (201 Created) is the full Asset record. The fields you’ll most often read:
{
  "id": "01J0...",
  "name": "perfume-bottle.webp",
  "mime_type": "image/webp",
  "size_bytes": 2400000,
  "url": "https://...",
  "thumbnail_url": "https://...",
  "asset_type": "image",
  "folder_id": null,
  "created_at": "2026-05-06T10:00:00Z"
}
4

Use the asset in a run

Reference it by id (or by url if the model accepts a public URL):
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "asset_id": "01J0...",
      "prompt": "white studio"
    },
    "callback_url": "https://your-server.com/webhook"
  }'

​
Verify it worked

curl https://api.runflow.io/v1/assets/{id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
A 200 with the Asset payload confirms it is usable.

​
Troubleshooting

SymptomLikely causeFix
403 on the PUTPresigned URL expiredRe-create with POST /v1/asset-uploads.
422 on createSize or MIME type rejectedsize_bytes max is 50 MiB; check mime_type against the supported list at GET /v1/assets/types.
Asset never confirmedConfirmation step skippedPOST to the confirmations endpoint.

Assets API

List, get, delete assets.

Asset folders

Organize uploads.