API reference
Request and response bodies are each maker's own format, passed through unchanged; their references are linked below. This page covers what's Veil's.
Routes
| Route | Body format | What it does |
|---|---|---|
POST /v1/chat/completions | OpenAI Chat Completions | A chat completion, streamed or not. |
POST /v1/responses | OpenAI Responses | A response, streamed or not. |
POST /v1/responses/compact | OpenAI Responses | Compacts a long conversation (on models that support it natively). |
POST /v1/messages | Anthropic Messages | A message, streamed or not. |
POST /v1/messages/count_tokens | Anthropic Messages | Counts tokens. Free. |
POST /v1/embeddings | OpenAI Chat Completions | Embeddings. |
POST /v1/images/generations | OpenAI Chat Completions | Generates images. Billed per image returned, or by the image tokens the model reports. |
POST /v1/images/edits | OpenAI Chat Completions | Edits images (multipart upload). Billed like generation, plus the input image tokens. |
POST /v1/audio/speech | OpenAI Chat Completions | Turns text into audio. Billed per input character. |
POST /v1/audio/transcriptions | OpenAI Chat Completions | Turns audio into text (multipart upload). Billed by audio tokens or seconds; use response_format json or verbose_json. |
POST /v1/videos | OpenAI Videos | Starts a video. GET reads its progress (or lists your videos) and DELETE removes it. |
GET /v1/videos/{id}/content | OpenAI Videos | Downloads a finished video, streamed from the provider. |
GET /v1/realtime | OpenAI Realtime | A realtime voice session over a WebSocket (wss). Send the key as a header, or from a browser as the openai-insecure-api-key sub-protocol. |
POST /v1/files | OpenAI Batch | Uploads a batch input (purpose batch, JSONL of /v1/chat/completions requests). GET, list and DELETE work as in OpenAI's files API. |
GET /v1/files/{id}/content | OpenAI Batch | Downloads a file: a batch's input, results or errors. |
POST /v1/batches | OpenAI Batch | Starts a batch from an uploaded file. GET lists your batches and reads one. |
POST /v1/batches/{id}/cancel | OpenAI Batch | Cancels a batch. Requests that already ran are charged; the rest are not. |
POST /v1/messages/batches | Anthropic Message Batches | Starts a batch of Messages requests. GET lists and reads them; cancel and DELETE work as in Anthropic's API. |
GET /v1/messages/batches/{id}/results | Anthropic Message Batches | Downloads a finished batch's results (JSONL). |
POST /v1beta/models/{model}:generateContent | Gemini | Generates content. |
POST /v1beta/models/{model}:streamGenerateContent | Gemini | Generates content as a stream. |
GET /v1/models | Veil | Every model you can call, with limits and prices. Free. |
GET /v1beta/models | Gemini | The same list, in Gemini's shape. Free. |
GET /v1/generations/{id} | Veil | A past request's model, tokens and cost. Free. |
GET /v1/key | Veil | The calling key's limits and spending this period. Free. |
Batches
A batch is up to 10,000 requests to one model, answered within 24 hours at the maker's batch price — half the list price for the makers that offer it. Only models whose price list has a batch rate take batches. When you start one, Veil holds the most the whole batch could cost; when it ends, you pay for the requests that ran, each at the batch rate, and the rest of the hold is released. Every request appears in Logs and Usage.
A batch runs after your request returns, so its requests and results are kept, encrypted with your organization's key: until an hour after you download the results, or 72 hours after the batch ends if you never do. An upload that never starts a batch is deleted after a day.
Video and realtime
A video is billed per second at its size. When you start one, Veil holds the price of every second you asked for; when the provider finishes, you pay for the seconds it rendered, and a video that fails costs nothing. Veil keeps no prompt, reference image or video: the video is streamed to you from the provider when you download it.
A realtime session holds a budget when it opens and is charged for each response's text and audio tokens, in and out. When the spend reaches the hold, Veil ends the session with an error event; start a new one to continue. However a session ends, including a dropped connection, you pay only for the responses that were produced.
Headers
Authorization / x-api-key / x-goog-api-key | Your Veil key, in whichever header your client sends. |
|---|---|
HTTP-Referer | Optional. Your app's URL, shown on the request in the console. |
X-Title | Optional. Your app's name, shown on the request in the console. |
x-veil-cost-usd | Added to non-streamed answers: what the request cost, in dollars. |
x-veil-provider | Added: the provider that answered. |
x-veil-generation-id | Added: the request's id, for /v1/generations and the console. |
x-veil-estimated | Added when a token count was estimated by Veil rather than counted by the provider. |
Errors
Errors come back in your client's own error format, with one of these statuses:
| 400 | The request is malformed, or no provider meets your privacy floor; the message says which. |
|---|---|
| 401 | No key, or the key is unknown, revoked or expired. |
| 402 | Not enough credit for the request. |
| 403 | This key may not use that model, or may not be used from this address. |
| 404 | Unknown model, or one with no price in force. |
| 413 | The request body is too large. |
| 429 | Too many requests for this key, or a spending cap or monthly budget is reached. |
| 503 | No provider for the model is available right now. Safe to retry. |