Upload large files

Three-step presigned upload for files too large for a JSON body.

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 size	Approach
< 1 MiB	Inline base64 or a public URL is fine.
1 MiB to 50 MiB	Inline if convenient, presigned upload if you control the server.
> 50 MiB	Not 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

Symptom	Likely cause	Fix
403 on the PUT	Presigned URL expired	Re-create with POST /v1/asset-uploads.
422 on create	Size or MIME type rejected	size_bytes max is 50 MiB; check mime_type against the supported list at GET /v1/assets/types.
Asset never confirmed	Confirmation step skipped	POST to the confirmations endpoint.

Related

Assets API

List, get, delete assets.

Asset folders

Organize uploads.