File and media input, output, and lifecycle

Beginner: four input methods

A URL fits an object already in storage. Base64 or a data URL fits a small one-off input. Multipart fits file forms such as transcription and image editing. An upstream Files API fits reusable uploads only when explicitly supported. The gateway /v1/files routes return not implemented, so an uploaded file ID cannot be assumed to work across models.

Copycurl "$BASE_URL/v1/audio/transcriptions"   -H "Authorization: Bearer $API_KEY"   -F "model=<MODEL_ID>"   -F "file=@sample.mp3"

Confirm the audio endpoint in the marketplace and follow the selected protocol for fields, MIME type, and format.

Support belongs to the endpoint

Chat vision may accept a remote or data URL. Image editing often uses multipart or a reference-image field. Transcription uses multipart. Video can use an image URL or a provider asset ID. Never copy a file_id, URL, or field from one successful protocol into another. Base64 magnifies payload, logging, and memory risks.

URL input security

Before server-side fetching, require HTTPS, resolve DNS, and reject loopback, private, link-local, and cloud metadata addresses. Repeat validation after every redirect. Bound redirects, connection and read timeouts, response bytes, and content type; a MIME header is not a substitute for magic-byte validation. Do not give an upstream provider a credential-bearing intranet URL.

Upload and memory

Stream multipart data, enforce request and per-file limits, and reject unsupported formats early. Do not load a large video into memory in one call. Temporary files need unguessable names, least privilege, and deterministic cleanup. Log size, digest, MIME, and object ID rather than full Base64 data or signed URLs.

Result lifecycle

A synchronous response may contain Base64 or a short-lived URL; an async task can return a binary result envelope. Validate status, type, length, and digest before streaming to owned storage. Delivery is complete only after the durable business copy succeeds. An expired or 410 download URL should not be retried forever.

Expert governance

Define data classes, allowed formats, malware scanning, decompression and image-bomb protection, tenant isolation, and deletion propagation. Record upstream provider, region, retention policy, task ID, and deletion time. Capacity planning must cover bandwidth, temporary disk, object storage, concurrent connections, and Base64 expansion—not only request count.