> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media inputs

> Provide an input image (or other media) for image-to-image and image-to-video models — by URL, upload, data URI, or base64.

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. |

<Note>
  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.
</Note>

## 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.

```bash theme={null}
curl https://api.budgetpixel.com/v1/uploads \
  -H "Authorization: Bearer bpx_live_xxx" \
  -F "file=@./cat.png"
```

```json theme={null}
{
  "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:

```bash theme={null}
curl https://api.budgetpixel.com/v1/videos/seedance-2.0 \
  -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:

```bash theme={null}
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](/concepts/rate-limits).
* Which models accept a media input, and under what parameter name, is listed on each
  model's API reference page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.