Media Uploads

Get a local file onto the Wireflow CDN so you can wire it into a workflow. Inline for small files, presigned direct-to-R2 for anything up to 25MB, or 100MB for video.

Last updated View as MarkdownAgent setup

Workflows consume media by URL. These endpoints put your file on cdn.wireflow.ai, which is already on the executor's host allowlist, so the returned url drops straight into an input:image / input:video / input:audio node or any media port.

All three doors return the same response shape, so pick one by file size and parse the result the same way:

{
  "url": "https://cdn.wireflow.ai/uploads/api/42/a1b2....png",
  "mediaId": "a1b2....png",
  "contentType": "image/png",
  "width": 1024,
  "height": 1024,
  "duration": null,
  "bytes": 812345
}

Which door to use

Your file Use Limit
Small, as a multipart file POST /media/upload with file=@... 4MB
Small, as a base64 dataUrl POST /media/upload with { "dataUrl" } 3MB
Image or audio, bytes in hand POST /media/upload-url → PUT → /complete 25MB
Video, bytes in hand POST /media/upload-url → PUT → /complete 100MB
Already hosted at a public URL POST /media/upload with { "url": "..." } 25MB

Why 4MB inline, when the presigned flow takes more? The API runs on serverless functions that reject a request body over roughly 4.5MB before any Wireflow code runs. Rather than let you discover that as an opaque platform error, the inline door refuses at 4MB and points you here. The presigned flow has no such ceiling because the bytes go straight from you to storage.

Send larger files through POST /api/v1/media/upload-url, PUT to the returned uploadUrl, then POST /api/v1/media/upload-url/complete. The inline multipart file cap is 4MB (4,194,304 bytes); the base64 dataUrl file cap is 3MB (3,145,728 decoded bytes). Multipart framing and JSON/base64 encoding also contribute to the request body. A body above the platform ceiling can be rejected before our handler runs, so that response may be a non-JSON platform error. Choose the presigned path before sending larger files; do not rely on receiving a JSON size error.

And why 3MB for a dataUrl? Same 4MB limit, different units. base64 puts about 4/3 of the file on the wire, and the limit is measured on the encoded body, so a dataUrl tops out around 3MB of actual file. A 3.6MB image is under "4MB" and still too big to send this way — use multipart, or the presigned flow.

Scope for every endpoint on this page: workflows:write. Uploads are listed by GET /media.

Inline upload

POST /api/v1/media/upload

Send one of:

  • multipart/form-data with a file field, up to 4MB
  • JSON { "dataUrl": "data:image/png;base64,..." }, up to 3MB of file (see above)
  • JSON { "url": "https://example.com/clip.mp4" }, we fetch and rehost it, up to 25MB for every type. A video over 25MB goes through the presigned flow below.
curl -X POST https://wireflow.ai/api/v1/media/upload \
  -H "Authorization: Bearer $WIREFLOW_API_KEY" \
  -F "file=@hook.png"

Optional width, height and duration fields are accepted as hints. They are only used when we cannot read the value out of the file itself, and they never override what we measured.

Presigned upload (up to 25MB, 100MB for video)

Three calls. Finish within 24 hours: an upload that never reaches step 3 is swept, along with its object, by a daily cleanup. The asset does not appear in GET /media until step 3 either.

1. Ask for a URL. bytes is the exact byte length of the file. A file over the limit for its type (25MB, or 100MB for video/*) is refused here with file_too_large, before anything is signed.

curl -X POST https://wireflow.ai/api/v1/media/upload-url \
  -H "Authorization: Bearer $WIREFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType":"video/mp4","bytes":18874368,"filename":"broll.mp4"}'
{
  "uploadUrl": "https://<signed-upload-url>",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4",
    "Content-Length": "18874368",
    "Cache-Control": "public, max-age=31536000, immutable"
  },
  "mediaId": "a1b2c3d4-....mp4",
  "url": "https://cdn.wireflow.ai/uploads/api/42/a1b2c3d4-....mp4",
  "contentType": "video/mp4",
  "bytes": 18874368,
  "expiresAt": "2026-08-18T12:15:00.000Z"
}

2. PUT the bytes to uploadUrl with exactly the headers you were given. The content type and the byte length are part of the signature, so a mismatch is rejected by storage with SignatureDoesNotMatch. The URL is valid for 15 minutes.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  -H "Content-Length: 18874368" \
  --data-binary @broll.mp4

3. Finalize.

curl -X POST https://wireflow.ai/api/v1/media/upload-url/complete \
  -H "Authorization: Bearer $WIREFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaId":"a1b2c3d4-....mp4"}'

This verifies the object landed, checks its size against the same limit, confirms an image is really a decodable image, and returns the standard response above. It is safe to retry.

If it answers unreadable_image, the bytes you PUT were not the image type you asked for. The object is discarded — mint a new upload url and send the real file.

Hourly budget

An account can mint up to 10GB of upload urls in a rolling hour. A mint counts for one hour from the moment it is made, whether or not you complete it. The count covers every upload made through these endpoints and through upload links. It is taken under a per-account lock, so a burst of parallel requests cannot get past the limit. Mints for one account are handled one at a time: a request that finds another one in progress waits its turn for up to about a second, and if it still has no turn it answers 429 with code upload_busy and Retry-After: 1. Retry it; nothing was signed and no row was written. Past the budget, POST /media/upload-url answers 429 with code upload_budget_exceeded and a Retry-After in seconds, and the message says when the oldest upload leaves the hour and room starts to come back. Nothing is signed and no row is written for a refused mint.

Metadata on the presigned path

Images get their width and height read from the file. Video dimensions and duration are measured server-side with bounded reads when the format is supported, including MP4. Audio duration is also measured server-side. Unmeasurable values return null; caller-supplied duration is never trusted. Optional width and height hints on /complete are bounded and only fill gaps in measured dimensions. Completion does not download an entire video just to measure it, and a video can be 100MB.

Accepted types

Images jpg, png, gif, webp, avif · video mp4, webm, mov · audio mp3, wav, m4a.

Anything else is refused with unsupported_type.

SVG

svg (image/svg+xml, max 1MB) is accepted by the inline door only, through any of its three forms (multipart, dataUrl, { "url": "..." }). It is made for brand logos.

We never store the file you sent. It is parsed and rebuilt from an allowlist of shape, gradient, clip, mask and use elements, and only that rebuilt markup is stored. Scripts, event handlers, foreignObject, <image>, links, animation, external and data: urls, @import, and DOCTYPE or entity declarations are removed. href survives only as a same-document #id. The returned bytes is the size of the stored, sanitized file. An SVG over 1MB, with more than 20,000 elements, or nested more than 64 deep is refused, never truncated.

The stored file is served as image/svg+xml with Content-Disposition: attachment, so it renders in an <img> or a composition but downloads if opened in a tab.

The presigned flow refuses SVG: it never sees the bytes, so it cannot sanitize them.

A paid image model needs pixels. When an SVG is wired into one, it is rasterized to PNG before the run is charged; if that cannot be done the run is refused, uncharged.

Errors

Code Meaning
unsupported_type The content type is not in the list above
file_too_large Over the limit for the door and file type you used
upload_budget_exceeded More than 10GB of upload urls minted in the last hour (HTTP 429)
upload_busy Another mint for this account kept its turn for about a second (HTTP 429, retry after Retry-After)
invalid_bytes bytes is missing or is not a positive whole number
invalid_media_id The mediaId is not one we minted
upload_not_found Unknown mediaId, the PUT never happened, or the 24h window lapsed
unreadable_image The bytes are not a decodable image of the type you declared
empty_file Zero bytes
invalid_svg Sent as SVG, but the root element is not <svg>
svg_too_complex SVG with more than 20,000 elements or nested more than 64 deep

Related

  • Upload a file

    Upload a local image or video with your API key, get its URL, and pass that URL as a workflow run input: up to 4MB in one call, or 100MB for video in 3 steps.

  • Run a workflow from your app

    To run an AI workflow from your app, send its inputs to POST /api/v1/workflows/{id}/run with your API key, poll the run, then download each output file.

  • Compositor contract

    Drive the free compv3 compositor over the API: node config shape, layers, stage size and the rendered PNG output.

  • Limits

    Wireflow's limits for uploads, runs and the API: file sizes per upload method, the 10GB hourly upload budget, route limits and what happens at a limit.

For AI agents: the full documentation index is at /llms.txt, and most docs pages are available as Markdown by adding .md to the URL.

© 2026 Wireflow. All rights reserved.