Skip to main content
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, audio, and 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:
EndpointFields that accept a file_id
POST /v3/imagesimage, mask, reference_images
POST /v3/audio/transcriptionsaudio
POST /v3/videosimage, video, reference_images
# 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

OperationEndpoint
Upload a filePOST /v3/files
List filesGET /v3/files
Get metadataGET /v3/files/{id}
Get a download URLGET /v3/files/{id}/content
Delete a fileDELETE /v3/files/{id}

​
What’s next

Images

Generate and edit images; feed a file_id for image-to-image.

Video

Seed a video from an uploaded or generated image.

Audio

Transcribe an audio file_id.

Multimodality

How the modalities fit together.