Skip to content

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:

  1. An x-provider header on the call, naming an Anthropic provider (rarely needed).
  2. Otherwise, the Anthropic provider whose Files API and batches setting is Served.
  3. Otherwise, if exactly one Anthropic provider is set up, that one.
  4. 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.