Media uploads
Optional storage helpers for publicly accessible media.
Media upload is deployment-dependent. Confirm availability before using these endpoints. Most AI integrations can use their provider's supported inline content or an existing hosted URL; see Images and files.
Upload
POST /v1/media/upload accepts multipart field file:
curl -sS https://api.tokamak.sh/v1/media/upload \
-H "Authorization: Bearer $TOKAMAK_API_KEY" \
-F "[email protected];type=image/png"Use a non-sensitive sample. The successful response is HTTP 200 with id, mime, bytes, deduped and url. Use the returned URL rather than constructing one.
Access and compatibility
The returned URL can be public. This API has no per-file publish step, expiring share-link operation or client deletion endpoint. Use storage with appropriate access controls for private content.
An uploaded media ID is not automatically a provider file ID. Tokamak does not insert uploaded content into arbitrary inference payloads.
The /v1/files upload/retrieval aliases use these media handlers; they are not a complete OpenAI Files API.
Read metadata
GET /v1/media/{id}/metadata returns id, url, content_type and size.
GET /v1/media/{id} returns either content bytes or a JSON object with url, depending on deployment configuration. Inspect the content type before saving the body as a file.