Files and uploads¶
Files you hand to a provider (batch inputs, fine-tuning data, documents) leave your network like any prompt. Through the gateway, each upload is recorded with its name, size and fingerprint, so you can show what was sent where, without Vidai ever keeping the file.
What it is¶
OpenAI's Files API (/v1/files: upload, list, retrieve, content, delete) and Uploads API (/v1/uploads: a large file in
parts). The gateway passes them on unchanged to OpenAI or Azure OpenAI. Batches and fine-tuning jobs refer to these
files by id, so they follow the same rule: see Batches and Fine-tuning.
Which provider holds your files¶
A file call names no model, so the gateway can't route it by model. A file lives with one provider, and every later call that names its id must reach the same one, so the choice is fixed, never a guess:
- The
x-providerheader, if you send one: the provider's name under Providers in the Control room. - Otherwise the provider set to serve files: Providers › (a provider) › Connection › Files API and batches › Served.
- Otherwise, the one OpenAI or Azure OpenAI provider, if there's exactly one.
- Otherwise a 400 that names the candidates and how to choose one.
With a single OpenAI or Azure OpenAI provider, standard SDK code works with no header and no setting. A provider set to Not served is never chosen, nor is one that's switched off.
Files are shared by every key. The provider keeps files under the one account the gateway uses for it, and it can't tell gateway keys apart. So any Vidai key can list, read and delete every file in that account, whichever key uploaded it.
The two settings¶
The same as for the OpenAI SDK: base address https://<your-gateway>/v1 and your Vidai key. See
OpenAI SDK for Python.
A minimal call¶
from openai import OpenAI
client = OpenAI()
uploaded = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
print(uploaded.id)
for f in client.files.list():
print(f.id, f.filename)
text = client.files.content(uploaded.id).text
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI();
const uploaded = await client.files.create({ file: fs.createReadStream("requests.jsonl"), purpose: "batch" });
console.log(uploaded.id);
for await (const f of client.files.list()) console.log(f.id, f.filename);
const text = await (await client.files.content(uploaded.id)).text();
curl https://<your-gateway>/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F purpose=batch -F file=@requests.jsonl
To choose the provider yourself, add the header: extra_headers={"x-provider": "openai-eu"} in Python,
{ headers: { "x-provider": "openai-eu" } } as the request options in TypeScript, -H "x-provider: openai-eu" in curl.
Large files¶
The Uploads API sends a file in parts: uploads.create, then uploads.parts.create for each part, then
uploads.complete. The Python SDK does all three for you with client.uploads.upload_file_chunked(...). Every part
goes to the same provider by the rule above.
Reading what the gateway did¶
Every answer carries x-vidai-request-id (paste it into Request logs › Request reference). Read it with
client.files.with_raw_response.create(...) (Python) or .withResponse() (TypeScript).
For every upload (files.create, and each part of an Upload), the gateway records the file's name, type, purpose,
size, SHA-256 (of the upload exactly as sent) and the provider's file id. Never the content: Vidai doesn't keep
the file, and the request log holds a summary of the form, not its bytes.
Errors¶
| Status | Code | When |
|---|---|---|
| 400 | bad_request |
Several providers could serve files and none is chosen; the message names them |
| 400 | bad_request |
x-provider names a provider of another kind (Anthropic, Gemini) |
| 400 | provider_override_not_allowed |
Your key is limited to some models, and x-provider names a provider that serves none of them |
| 404 | endpoint_not_found |
A near miss in the path |
| 413 | payload_too_large |
The upload is over the gateway's size limit; use the Uploads API |
The other codes are those of Chat Completions.
What goes through the gateway¶
| Feature | Through the gateway |
|---|---|
| Files: upload, list, retrieve, content, delete | Yes, to the provider chosen by the rule above |
| Uploads: create, parts, complete, cancel | Yes, the same way |
| Anthropic's Files API (same path, Anthropic SDK) | Yes, but only to an Anthropic provider, see Anthropic Messages |
| Files on Gemini | Through the Gemini format, see Gemini generateContent |
Check it works in a minute¶
curl https://<your-gateway>/v1/files -H "Authorization: Bearer $OPENAI_API_KEY"
A list (perhaps empty) means the address and key are right and a provider serves files.
Good to know¶
- The gateway never tries a fallback for files, uploads or batches: a failure comes straight back to you.
- Guardrails don't scan file content.
- On Azure OpenAI, files go to the resource's own files address with the provider's API version; no deployment is involved.
- An upload from the Anthropic SDK is never sent to OpenAI, even when OpenAI is the only provider that serves files.