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

# Files

> Reusable storage for media. Upload once, reference by id across image, audio, and video calls.

Files are how media moves between calls on Opper. Upload a file (or let a generation store its output) and you get back a `file_<id>` — a reusable handle you can pass as input to later calls instead of re-uploading or re-encoding bytes. One uploaded image can seed a video; one generated image can be edited by the next call; a generated audio clip can be fed straight to transcription.

## Two ways files appear

* **You upload them.** `POST /v3/files` (multipart) returns a `file_<id>` for reference media — an image to animate, a source video to edit, an audio clip to transcribe.
* **Generations store them.** The [image](/build/multimodal/images), [audio](/build/multimodal/audio), and [video](/build/multimodal/video) endpoints save their output to Files by default (`store: true`) and return a `file_id` alongside the result. Set `store: false` to opt out.

## Using a `file_id` as input

A `file_id` is accepted anywhere a media source is — next to an http(s) URL or a data-URI:

| Endpoint                                                   | Fields that accept a `file_id`       |
| ---------------------------------------------------------- | ------------------------------------ |
| [`POST /v3/images`](/build/multimodal/images)              | `image`, `mask`, `reference_images`  |
| [`POST /v3/audio/transcriptions`](/build/multimodal/audio) | `audio`                              |
| [`POST /v3/videos`](/build/multimodal/video)               | `image`, `video`, `reference_images` |

```bash theme={null}
# 1. Upload a reference image
curl -sX POST https://api.opper.ai/v3/files \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -F "file=@cat.jpg"
# → { "id": "file_abc123", ... }

# 2. Use it as the seed for a video
curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "openai/sora-2", "prompt": "the cat blinks slowly", "image": "file_abc123" }'
```

## Lifecycle and retention

Files expire after a default TTL, capped by your project's retention. On zero-data-retention projects, storing is skipped — uploads and stored outputs degrade gracefully, and generation responses tell you when an output wasn't persisted. Delete files you no longer need with `DELETE /v3/files/{id}`.

## Quotas

Each organization has a storage quota — a total byte budget (it can vary by plan) and a cap on the number of files. Uploads and stored generation outputs draw from the same budget.

* **Uploads** that would exceed the quota are rejected with `413`.
* **Generated outputs** (`store: true`) degrade gracefully when the quota is full: the call still succeeds and returns the result inline, it just isn't persisted — the response signals the skip rather than failing.

Because generated media carries a short TTL, the quota self-relieves as files expire. To free space sooner, delete files you no longer need. Quota relief and larger budgets are tied to your plan.

## Operations

| Operation          | Endpoint                                                                 |
| ------------------ | ------------------------------------------------------------------------ |
| Upload a file      | [`POST /v3/files`](/v3-api-reference/files/upload-file)                  |
| List files         | [`GET /v3/files`](/v3-api-reference/files/list-files)                    |
| Get metadata       | [`GET /v3/files/{id}`](/v3-api-reference/files/get-file)                 |
| Get a download URL | [`GET /v3/files/{id}/content`](/v3-api-reference/files/get-file-content) |
| Delete a file      | [`DELETE /v3/files/{id}`](/v3-api-reference/files/delete-file)           |

## What's next

<CardGroup cols={2}>
  <Card title="Images" icon="palette" href="/build/multimodal/images">
    Generate and edit images; feed a `file_id` for image-to-image.
  </Card>

  <Card title="Video" icon="film" href="/build/multimodal/video">
    Seed a video from an uploaded or generated image.
  </Card>

  <Card title="Audio" icon="waveform-lines" href="/build/multimodal/audio">
    Transcribe an audio `file_id`.
  </Card>

  <Card title="Multimodality" icon="shapes" href="/build/multimodal/overview">
    How the modalities fit together.
  </Card>
</CardGroup>