Skip to content

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:

  1. The x-provider header, if you send one: the provider's name under Providers in the Control room.
  2. Otherwise the provider set to serve files: Providers › (a provider) › Connection › Files API and batches › Served.
  3. Otherwise, the one OpenAI or Azure OpenAI provider, if there's exactly one.
  4. 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.