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

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

## Notes

* Uploads are **not** charged — you're billed only when a generation succeeds.
* The same plan access and rate limits that apply to generation apply to uploads.
* Which models accept a media input, and under what parameter name, is listed on each
  model's API reference page.