Files (Anthropic)¶
Anthropic's Files API lets you upload a document once and refer to it by id in later messages. Through the gateway the same SDK calls work with your Vidai key, and every file goes to an Anthropic provider and only there, never to another vendor that happens to serve the same path.
What it is¶
The Files API (a beta at Anthropic): POST /v1/files to upload, GET /v1/files to list, GET /v1/files/{id} for a
file's details, GET /v1/files/{id}/content to download, DELETE /v1/files/{id} to delete. The SDK always sends
anthropic-version; Anthropic's own examples add anthropic-beta: files-api-2025-04-14.
OpenAI's Files API uses the same /v1/files path. The gateway tells them apart by those two Anthropic headers: a call
that carries either one is an Anthropic file call.
The two settings¶
The same as for Messages: ANTHROPIC_BASE_URL (base_url, baseURL) set to https://<your-gateway>,
and ANTHROPIC_API_KEY (api_key, apiKey) set to your Vidai key.
Which provider holds the file¶
A file call names no model, so the gateway can't choose a provider from a model name. It decides like this, and never guesses:
- An
x-providerheader on the call, naming an Anthropic provider (rarely needed). - Otherwise, the Anthropic provider whose Files API and batches setting is Served.
- Otherwise, if exactly one Anthropic provider is set up, that one.
- Otherwise a 400 that names the candidates; an admin sets Files API and batches to Served on one of them under Providers.
With one Anthropic provider, the common case, it just works: no header, no setting. A file is never sent to OpenAI, Bedrock or Vertex AI (they have no Anthropic Files API), even if no Anthropic provider exists: the call gets a 400.
A minimal call¶
import anthropic
client = anthropic.Anthropic()
uploaded = client.beta.files.upload(
file=("policy.pdf", open("policy.pdf", "rb"), "application/pdf"),
)
print(uploaded.id)
message = client.beta.messages.create(
model="claude-sonnet-4.5",
max_tokens=300,
betas=["files-api-2025-04-14"],
messages=[{"role": "user", "content": [
{"type": "text", "text": "Summarise this policy in three lines."},
{"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
]}],
)
print(message.content[0].text)
import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";
const client = new Anthropic();
const uploaded = await client.beta.files.upload({
file: await toFile(fs.createReadStream("policy.pdf"), "policy.pdf", { type: "application/pdf" }),
});
const message = await client.beta.messages.create({
model: "claude-sonnet-4.5",
max_tokens: 300,
betas: ["files-api-2025-04-14"],
messages: [{ role: "user", content: [
{ type: "text", text: "Summarise this policy in three lines." },
{ type: "document", source: { type: "file", file_id: uploaded.id } },
] }],
});
curl https://<your-gateway>/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
-F "[email protected]"
Listing, details, download and delete are client.beta.files.list(), .retrieve_metadata(id), .download(id) and
.delete(id) in Python (list, retrieveMetadata, download, delete in TypeScript).
Reading what the gateway did¶
Every file call carries x-vidai-request-id; x-vidai-provider-key names the provider key used (its label, never the
secret). Read them with with_raw_response (Python) or .withResponse() (TypeScript), as on
Messages.
Errors¶
In Anthropic's shape ({"type":"error","error":{"type":…}}). Match on x-vidai-error-code:
| Status | Code | Why |
|---|---|---|
| 400 | bad_request |
No Anthropic provider serves files, or several do and none is chosen (the message names them), or x-provider names a provider of another vendor |
| 401, 403 | key codes | As on Messages |
What goes through the gateway¶
| Call | Anthropic | Bedrock, Vertex AI, other vendors |
|---|---|---|
| Upload, list, details, download, delete | Yes | No: a 400, nothing sent |
A file_id in a message |
Yes, to Claude on the Anthropic provider that holds the file | Use base64 content instead: sent to another provider's model, the call isn't refused, but that model can't open the file and x-vidai-adapted doesn't say so |
Check it works in a minute¶
curl -s https://<your-gateway>/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
A JSON list (empty is fine) means files reach your Anthropic provider.
Good to know¶
- Files are shared across keys. The provider stores them under the one account the gateway uses, so any Vidai key can list, read and delete every file there, whichever key uploaded it.
- Never retried on another model or provider: a file belongs to the provider that holds it.
- Guardrails don't read file contents.