Media inputs

Some models take an input media parameter in addition to the prompt — for example, the image parameter on an image-to-image or image-to-video request. Every media parameter accepts the same four forms, so you can use whichever fits your app:

Form	When to use
Uploaded-file URL	You have a local file and no public URL. Upload it once (below), pass the returned `url`.
Public URL	The image already lives at a public `https://` address. Pass it directly.
Data URI	Small inline images: `data:image/png;base64,iVBORw0...`
Raw base64	The bare base64 string, no prefix.

Uploaded files and a model’s outputs are ephemeral — stored privately and deleted about 24 hours after creation. Re-upload if you need them again.

Option 1 — Upload a file

POST /v1/uploads accepts a multipart/form-data body with a single file field (image, video, or audio; max 50 MB) and returns a short-lived URL.

curl https://api.budgetpixel.com/v1/uploads \
  -H "Authorization: Bearer bpx_live_xxx" \
  -F "file=@./cat.png"

{
  "url": "https://cdn.budgetpixel.com/api-inputs/9f2c....png?...",
  "content_type": "image/png",
  "bytes": 482113,
  "expires_in": 86400
}

Then pass that url as the media parameter:

curl https://api.budgetpixel.com/v1/videos/seedance-1.5-pro \
  -H "Authorization: Bearer bpx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a gentle zoom out, cinematic",
    "image": "https://cdn.budgetpixel.com/api-inputs/9f2c....png?..."
  }'

Option 2 — Pass a public URL or base64 directly

No upload step needed — hand the model a public URL, a data URI, or raw base64:

curl https://api.budgetpixel.com/v1/images/flux-2-pro \
  -H "Authorization: Bearer bpx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "turn this into a watercolor painting",
    "image": "https://example.com/photo.jpg"
  }'

When you pass a URL, our servers fetch it for you, so it must be publicly reachable over http/https. Private, loopback, and internal addresses are rejected.

Accepted formats

Image — PNG, JPEG, WebP, GIF
Video — MP4, WebM
Audio — MP3, WAV, OGG

The file type is detected from its contents, not its name or the Content-Type you send. A media parameter only accepts media of the matching kind (an image parameter requires an image).

Image inputs are resized automatically

Input images whose longest edge is over 2048 px, or that are larger than 4 MB, are downscaled for you before the model sees them. Very large inputs (a 4K photo straight off a phone) make generations slow and can time them out, without improving the result — models work at or below this resolution internally either way.

The aspect ratio is preserved, so match_input_image and similar options behave exactly as they would on the original.
Images already within those limits are passed through byte for byte.
Transparency is preserved: a PNG that uses an alpha channel stays a PNG.
Output resolution is unaffected — it comes from the model’s own size parameters, not from the input image.

Send full-resolution images if that’s what you have; there’s no benefit to shrinking them yourself first.

Notes

Uploads are not charged — you’re billed only when a generation succeeds.
Uploading requires the same plan access as generation. Because uploads are free, POST /v1/uploads also has a dedicated 60 uploads/min per account cap (a rolling window) on top of the global request limits — see Rate limits.
Which models accept a media input, and under what parameter name, is listed on each model’s API reference page.

Get Started

MCP

Concepts

Option 1 — Upload a file

Option 2 — Pass a public URL or base64 directly

Accepted formats

Image inputs are resized automatically

Notes

​Option 1 — Upload a file

​Option 2 — Pass a public URL or base64 directly

​Accepted formats

​Image inputs are resized automatically

​Notes

Option 1 — Upload a file

Option 2 — Pass a public URL or base64 directly

Accepted formats

Image inputs are resized automatically

Notes