A1 API Gateway — Integration Guide

1. What the gateway is
2. Setup in five minutes
3. Endpoints
4. Model names and aliases
5. Which endpoint to use
6. Features
7. What comes back in the headers
8. Errors and what to do about them
9. Limits, budgets and money
10. What is not supported
11. Getting and checking a key
12. Telling your AI assistant

1. What the gateway is

A1 API Gateway is the company's single door to the AI vendors — Anthropic, OpenAI and xAI for chat, OpenAI for pictures and embeddings, ElevenLabs, AssemblyAI and OpenAI for speech and transcription. Your project never holds a vendor key. It holds a gateway key that starts with sk-gw-, sends requests to the gateway in the vendor's own format, and the gateway does the rest: checks the key and the caller's IP, applies rate limits and spending caps, forwards the request with the real vendor key, measures the exact cost, and returns the vendor's answer unchanged.

2. Setup in five minutes

2.1 Two environment variables

AI_GATEWAY_URL=https://api.a1apigateway.com        # local development: http://127.0.0.1:8080
AI_GATEWAY_KEY=sk-gw-xxxxxx-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The production address is https://api.a1apigateway.com. Keep it in an environment variable so a local or staging gateway can be swapped in without code changes.

2.2 Change two lines in your SDK setup

Keep using the SDK you already use. Point it at the gateway and hand it the gateway key.

// TypeScript                                        # Python
import OpenAI from "openai";                         from openai import OpenAI

const ai = new OpenAI({                              ai = OpenAI(
  apiKey: process.env.AI_GATEWAY_KEY,                    api_key=os.environ["AI_GATEWAY_KEY"],
  baseURL: `${process.env.AI_GATEWAY_URL}/v1`,           base_url=f"{os.environ['AI_GATEWAY_URL']}/v1",
});                                                  )

const res = await ai.chat.completions.create({       res = ai.chat.completions.create(
  model: "anthropic/claude-opus-5",                      model="anthropic/claude-opus-5",
  max_tokens: 1024,                                      max_tokens=1024,
  messages: [{ role: "user", content: "…" }],            messages=[{"role": "user", "content": "…"}],
});                                                  )

// TypeScript                                        # Python
import Anthropic from "@anthropic-ai/sdk";           import anthropic

const ai = new Anthropic({                           ai = anthropic.Anthropic(
  apiKey: process.env.AI_GATEWAY_KEY,                    api_key=os.environ["AI_GATEWAY_KEY"],
  baseURL: process.env.AI_GATEWAY_URL,                   base_url=os.environ["AI_GATEWAY_URL"],
});                                                  )

const res = await ai.messages.create({               res = ai.messages.create(
  model: "anthropic/claude-opus-5",                      model="anthropic/claude-opus-5",
  max_tokens: 1024,                                      max_tokens=1024,
  messages: [{ role: "user", content: "…" }],            messages=[{"role": "user", "content": "…"}],
});                                                  )

curl "$AI_GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-5","max_tokens":256,"messages":[{"role":"user","content":"ping"}]}'

That is the whole integration. Everything below is detail you will want when something surprises you.

3. Endpoints

Authentication is either Authorization: Bearer sk-gw-… or x-api-key: sk-gw-… — both SDKs already send one of them.

4. Model names and aliases

Names are provider/model: anthropic/claude-opus-5, openai/gpt-5.6, xai/grok-4.3, openai/text-embedding-3-small, elevenlabs/eleven_flash_v2_5, assemblyai/universal-3-5-pro. The prefix can be left off when the name is unambiguous (claude-…, gpt-…, o…, grok-…, text-embedding-…, tts-…, whisper-…). ElevenLabs and AssemblyAI models always need their prefix: a bare eleven_flash_v2_5 or universal-2 is 404 model_not_found.

Your gateway admin can also define aliases for your organisation — for example settlement-default pointing at whatever model the team has standardised on. Use the alias in production code: when the team moves to a newer model the admin changes the alias and nothing in your project needs a deploy. The x-gw-model response header always tells you which real model answered.

GET /v1/models lists exactly what your key is permitted to use. A name that does not exist gives 404 model_not_found; one that exists but is not allowed for your key gives 403 model_not_allowed.

4.1 Capabilities — check, don't guess

Every model in the list carries a capabilities block saying what you may send to it, so a client can check up front instead of discovering a 400 in production:

{"id":"anthropic/claude-opus-5","object":"model","owned_by":"anthropic",
 "capabilities":{"streaming":true,"images":true,"documents":true,"tools":true,"structured_output":true,
                 "reasoning":true,"prompt_caching":true,"sampling_params":false,"forced_tool_choice":true,
                 "endpoints":["/v1/chat/completions","/v1/messages","/v1/messages/count_tokens"]}}

true and false are asserted by the gateway; null means the gateway does not know and the vendor decides. documents means PDFs and text documents as file content parts (§6.3b); prompt_caching means repeated context is billed at the cached rate (§6.3c); endpoints lists which consumer endpoints accept the model — exactly one for image, embedding, speech and transcription models. Those models report every other flag as false (nothing streams on their endpoints), except sampling_params, which is true for transcription models (temperature). The block is an extra field on the standard OpenAI list entry, so OpenAI-shaped clients simply ignore it.

{"id":"openai/text-embedding-3-small","object":"model","owned_by":"openai",
 "capabilities":{"streaming":false,"images":false,"documents":false,"tools":false,"structured_output":false,
                 "reasoning":false,"prompt_caching":false,"sampling_params":false,"forced_tool_choice":false,
                 "endpoints":["/v1/embeddings"]}}

4.2 One model, one door

Every model in the catalogue does one kind of thing and answers on the endpoint for that thing only:

A model sent to the wrong endpoint is refused before any vendor call with 400 invalid_request, and the message names the right one:

Model 'text-embedding-3-small' is an embedding model and answers on POST /v1/embeddings, not /v1/chat/completions.

4.3 Prices worth knowing

The catalogue was re-read from the vendors' own price pages on 19 September 2026.

• Long context is billed at the higher rate for the whole request. xAI charges every text model double (input and output) once the prompt is over 200K tokens; OpenAI charges 2× input and 1.5× output over 272K prompt tokens on its newer models (gpt-6-astra, gpt-5.6, gpt-5.6-sol / -terra / -luna, gpt-5.5, gpt-5.4). The gateway picks the rate from the vendor's own prompt count (input + cached + cache-write tokens), and reserves at the higher rate when the estimated prompt is already over the line — so a large prompt can meet 402 request_too_expensive sooner than its short-context price suggests.
• gpt-5.6 is $4 input / $0.40 cached / $20 output per 1M tokens (it was priced at $5 / $0.50 / $30). It is OpenAI's alias for GPT-5.6 Sol, at a promotional price OpenAI states runs at least until 21 November 2026.
• Retired xAI names bill as grok-4.3. xAI retired grok-4, grok-4-fast and grok-3 on 15 May 2026 and now serves and bills them as grok-4.3 ($1.25 / $0.20 / $2.50 per 1M tokens), so that is what they cost here. Move to xai/grok-4.3 or a newer model by name.
• grok-3-mini is switched off — it is on no current xAI price list. Requests for it are 404 model_not_found.

Corrections apply from 19 September 2026; requests already made keep the price they were charged. x-gw-cost-usd is always what you were actually charged.

5. Which endpoint to use

/v1/messages exists for the rare Claude-only feature the OpenAI format cannot express — citations, anthropic-beta features, vendor server tools. It forwards the body untouched, which also means price-changing fields reach the vendor unpriced. Ask the gateway admin before using it.

For Claude models, /v1/chat/completions is translated; the few OpenAI-only parameters that have no equivalent are listed in §10, and every ignored field is reported in x-gw-warnings — nothing is dropped silently.

Pictures, embeddings, speech and transcription each have a door of their own. A model sent to the wrong one is a 400 invalid_request that names the right one (§4.2).

6. Features

6.1 Conversations

Both endpoints are stateless. Send the whole history on every call — system prompt, earlier user and assistant turns, then the new message. On /v1/chat/completions the system prompt is a message with role: "system"; on /v1/messages it is the top-level system field.

6.2 Streaming

Add "stream": true (or use the SDK's streaming helper). Text arrives as it is generated, exactly as from the vendor. At the end of the stream the gateway adds one extra line before [DONE]:

: x-gw-cost-usd=0.000146 x-gw-billing=byok

It starts with a colon, which makes it an SSE comment: every SDK ignores it, so it never breaks parsing. Read it only if you want the cost of a streamed call.

6.3 Images

JPEG, PNG, GIF and WebP, either inline as base64 or as an https:// URL, in the vendor's usual content-part shape (image_url on the OpenAI door, image + source on the Anthropic door).

6.3b PDFs and documents

Send the document inline as a file content part with a base64 data URL. PDFs and text types (plain text, Markdown, JSON, CSV, YAML, XML) are accepted; the gateway converts them to Claude's document block, with the filename as the title, and passes them through for OpenAI models. Other types — Word, Excel — are refused with 400 naming the media type, and file_id references are refused because there is no Files API through the gateway.

{"model":"anthropic/claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":[
  {"type":"file","file":{"filename":"contract.pdf","file_data":"data:application/pdf;base64,JVBERi0xLjQK…"}},
  {"type":"text","text":"What is the termination notice period?"}]}]}

Cost is reserved per page (worst case 4,600 tokens a page — the text plus the page as an image) and settled to the real usage afterwards. Anthropic accepts up to 32 MB and 100 pages per PDF on 200K-context models; the gateway accepts 20 MB bodies.

6.3c Prompt caching — automatic

Repeated context — a long system prompt, a big tool list, the earlier turns of a conversation — is cached by Anthropic and billed at 10 % of the input price on the next call within five minutes (refreshed on each use). The gateway turns this on for every Claude request; you do nothing. Writing the cache costs 1.25× on the cached prefix once, so it pays for itself on the second call.

• Only prefixes above the model's minimum (1,024–4,096 tokens, depending on the model) are cached. Shorter ones are simply not cached — nothing fails.
• Order matters: stable content first (system prompt, tools), then history, then the new message. Everything before the first changed byte is cached; everything after it is not.
• Check it works: usage.prompt_tokens_details.cached_tokens in the response is non-zero on a cache hit.
• Opt out per request with "cache_control": false; pass {"type":"ephemeral","ttl":"1h"} for the one-hour tier.

6.4 Tool calling

OpenAI-style tools and tool_choice are translated for Claude; the reply comes back as tool_calls with finish_reason: "tool_calls", and you continue with role: "tool" messages as usual. strict: true on a function is honoured — the vendor then guarantees the arguments match the schema. Only tools[].type: "function" is supported; the legacy functions / function_call API is rejected.

6.5 Structured JSON output

response_format: {"type": "json_schema", …} is mapped to Claude's structured output and the answer is guaranteed to match the schema. {"type": "json_object"} has no Claude equivalent, so the gateway appends a system instruction asking for a single JSON object and sets a warning — a request, not a guarantee. Use a schema when the shape matters.

6.6 Reasoning

reasoning_effort on /v1/chat/completions maps to Claude's adaptive thinking: none disables it; low, medium, high, xhigh, max set the effort; minimal becomes low. Omitted means the model's default. On models without adaptive thinking (Haiku 4.5, Sonnet 4.5 and older) the level becomes a fixed thinking budget instead (1,024 to 32,000 tokens, kept below max_tokens) and temperature / top_p are dropped — both reported in x-gw-warnings; if max_tokens leaves no room, thinking is skipped with a warning. On /v1/messages, send thinking / output_config as Anthropic documents them.

6.7 Counting tokens before you send

POST /v1/messages/count_tokens takes the same model, system, messages and tools you are about to send and returns {"input_tokens": 21}. It is free at the vendor, so the gateway charges nothing and holds no budget for it — it only counts against your requests-per-minute and shows in the request log at cost 0. Claude models only. Both SDKs' helpers work unchanged: ai.messages.countTokens(…) in TypeScript, ai.messages.count_tokens(…) in Python. Use it to estimate a call's cost — input tokens times the input price, plus max_tokens times the output price — before deciding to make it.

6.8 Sampling and max_tokens

temperature, top_p and stop pass through (Anthropic's temperature range is 0–1; higher values are clamped with a warning; the newest Claude models accept none of these and they are dropped with a warning). max_tokens falls back to your key's default when omitted and is refused when above your key's maximum.

6.9 Generating images

POST /v1/images/generations — OpenAI's own path and body, forwarded as sent. The reply is the vendor's, unchanged: each picture is in data[].b64_json. The OpenAI SDK works without modification (client.images.generate({…}) against the gateway's base URL).

curl "$AI_GATEWAY_URL/v1/images/generations" \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "model": "openai/gpt-image-2.5-flare",
        "prompt": "a single ripe lemon on a white marble counter, morning light",
        "n": 1,
        "size": "1024x1024",
        "quality": "low"
      }'

Models. gpt-image-2.5-flare (fast, the sensible default) and gpt-image-2.5-sunburst (highest quality); gpt-image-2 is still priced. Prefixed or bare model ids both work. DALL·E is not available — OpenAI removed dall-e-2 and dall-e-3 from the API on 12 May 2026.

Your key's image settings

Image generation is off by default on every key. An admin switches it on per key, together with ceilings on how many pictures per request, how large, at what quality, which image models, and an optional cost cap. Read your own from GET /v1/key and check at startup rather than discovering a limit in production:

"images": {
  "allowed": true,
  "max_images_per_request": 2,
  "max_size": "1536x1024",
  "max_quality": "high",
  "max_cost_per_request_usd": null,
  "allowed_models": []
}

allowed_models: [] means every image model the key may already use. A request over any ceiling is refused before a vendor is called, so it costs nothing.

What comes back when it is refused

Cost and timing

Billed in tokens like everything else: the prompt at the model's input rate, the pictures at its output rate, so x-gw-cost-usd is exact. Unlike chat, the worst case is known before the call — how many pictures, how large and at what quality are all in the body — so the reservation is tight rather than a guess.

6.10 Embeddings

POST /v1/embeddings — OpenAI's own path and body. The body goes to OpenAI exactly as you sent it, with only model rewritten to the vendor's id, and OpenAI's reply comes back unchanged.

curl "$AI_GATEWAY_URL/v1/embeddings" \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "openai/text-embedding-3-small",
        "input": ["Clause 4 limits liability to the fees paid.", "Payment is due within 30 days."]
      }'

{"object":"list",
 "data":[{"object":"embedding","index":0,"embedding":[-0.0061,0.0142,…]},
         {"object":"embedding","index":1,"embedding":[0.0217,-0.0093,…]}],
 "model":"text-embedding-3-small",
 "usage":{"prompt_tokens":19,"total_tokens":19}}

// TypeScript                                        # Python
const res = await ai.embeddings.create({             res = ai.embeddings.create(
  model: "openai/text-embedding-3-small",                model="openai/text-embedding-3-small",
  input: ["Clause 4 …", "Payment is due …"],             input=["Clause 4 …", "Payment is due …"],
});                                                  )
const vectors = res.data.map((d) => d.embedding);    vectors = [d.embedding for d in res.data]
// number[] each, 1536 long                          # list[float] each, 1536 long

Models and prices — per 1M input tokens. Nothing is generated, so there is no output price. The prefix is optional.

Floats or base64. The gateway sends encoding_format only if you did: ask for nothing and you get arrays of floats, ask for base64 and you get base64 strings, untouched. The gateway never switches to base64 behind your back. (The OpenAI SDKs do so themselves: when you leave encoding_format out, embeddings.create asks for base64 on the wire and decodes it back into floats for you. That works unchanged through the gateway. With curl or a plain HTTP client you get floats unless you ask.)

What is billed. usage.prompt_tokens from OpenAI's reply, at the model's input rate, and nothing else. Before the call the gateway reserves an over-estimate — text at one token per 3 bytes, token-id arrays at their exact length — which counts against your per-request cap, then settles to the real count. x-gw-cost-usd is exact.

Limits OpenAI enforces: 8,192 tokens per input, 2,048 inputs per request, 300,000 tokens across all inputs in one request. The gateway does not pre-check these; OpenAI's refusal comes back as 400 invalid_request prefixed The provider rejected the request:. The gateway's own body limit is 20 MB (413 request_too_large). Split large batches into several requests.

Retries and logging. The gateway retries once itself on a transient vendor failure (a 5xx or a dropped connection) — safe, because an embedding is idempotent. On a key that logs at full, the input is kept but the vectors are not.

What comes back when it is refused

6.11 Speech

POST /v1/audio/speech — OpenAI's speech request, answered by ElevenLabs or by OpenAI's tts-1 / tts-1-hd. The reply is the audio itself: raw bytes with the vendor's Content-Type (audio/mpeg for mp3), not JSON. Errors are JSON as usual, so check the status before writing the body to a file.

curl "$AI_GATEWAY_URL/v1/audio/speech" \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "elevenlabs/eleven_flash_v2_5",
        "voice": "narrator",
        "input": "Your settlement has been approved and will be paid on Friday.",
        "response_format": "mp3"
      }' \
  --fail-with-body --output reply.mp3

// TypeScript                                        # Python
import { writeFile } from "node:fs/promises";

const res = await ai.audio.speech.create({           res = ai.audio.speech.create(
  model: "elevenlabs/eleven_flash_v2_5",                 model="elevenlabs/eleven_flash_v2_5",
  voice: "narrator",                                     voice="narrator",
  input: "Your settlement has been approved …",          input="Your settlement has been approved …",
  response_format: "mp3",                                response_format="mp3",
});                                                  )
await writeFile("reply.mp3",                         res.write_to_file("reply.mp3")
  Buffer.from(await res.arrayBuffer()));

Models and prices — per character of input. ElevenLabs models need the elevenlabs/ prefix.

The voice

• OpenAI models: voice goes to OpenAI unchanged — alloy, echo, nova and the rest of OpenAI's names.
• ElevenLabs models: voice is either a name your organisation has set up in the console under Providers → ElevenLabs → Voices (say narrator, pointing at an ElevenLabs voice; matched exactly, case included — an admin can point it at a different voice later with no change to your code), or a raw ElevenLabs voice id — exactly 20 letters and digits, e.g. 21m00Tcm4TlvDq8ikWAM. Anything else is 400 invalid_request, and the message lists your organisation's voice names.
• OpenAI's names do not carry over: "voice": "alloy" with an elevenlabs/… model is refused, unless your organisation has named one of its voices alloy.
• voice must be a string. OpenAI's custom-voice object ({"id": "voice_…"}) is refused with 400.
• A voice cloned in an ElevenLabs account can only be used through that account's key. If your organisation cloned it, requests must route to the organisation's own ElevenLabs key — GET /v1/key → routing.elevenlabs shows which key is used.

For OpenAI models the body is forwarded as sent (only model rewritten). For ElevenLabs models only the fields above are used.

What is billed. The characters of input at the model's rate, counted as Unicode code points (an emoji is one character). The count is known before the call, so the reservation is exact. For ElevenLabs, the vendor's own figure wins when it reports one (the character-cost response header): a Voice Library voice with a custom rate costs more characters than the text has. x-gw-cost-usd is exact. As a guide, 1,000 characters cost $0.05 on Flash, $0.10 on v3 or Multilingual v2 and $0.015 on tts-1.

Access and limits. Any AI key whose model allowlist includes the model may use it; unlike images, audio has no separate switch on the key. Tokens per minute does not apply — there are no x-ratelimit-*-tokens headers — but requests per minute, concurrency, budgets and credit do. On a key that logs at full, the text is kept, never the audio.

What comes back when it is refused

6.12 Transcription

POST /v1/audio/transcriptions — OpenAI's transcription upload, answered by AssemblyAI, ElevenLabs Scribe or OpenAI's whisper-1. Send multipart/form-data with the audio in file, exactly as for OpenAI.

curl "$AI_GATEWAY_URL/v1/audio/transcriptions" \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -F model=assemblyai/universal-3-5-pro \
  -F file=@call-recording.mp3 \
  -F response_format=json \
  --max-time 900

{"text":"Hello, I'm calling about settlement S-1042…","usage":{"type":"duration","seconds":184}}

// TypeScript
import { createReadStream } from "node:fs";

const t = await ai.audio.transcriptions.create(
  { model: "assemblyai/universal-3-5-pro", file: createReadStream("call-recording.mp3"), language: "en" },
  { timeout: 15 * 60 * 1000 }, // AssemblyAI can take up to 10 minutes: wait longer than the gateway does
);
console.log(t.text);

# Python
with open("call-recording.mp3", "rb") as f:
    t = ai.with_options(timeout=900).audio.transcriptions.create(  # wait longer than the gateway's 10 minutes
        model="assemblyai/universal-3-5-pro",
        file=f,
        language="en",
    )
print(t.text)

Models and prices — per second of audio, rounded up to a whole second. AssemblyAI and ElevenLabs models need their prefix.

Every format works with every vendor

The gateway renders the five formats itself from the vendor's answer, so subtitles from AssemblyAI or ElevenLabs have the same shape as from whisper-1.

For AssemblyAI and ElevenLabs, segments and subtitle cues are built from the word timings: a cue ends at the end of a sentence, at a pause of more than a second, or at 7 seconds or 16 words. whisper-1's own segments are used as they are. language is whatever the vendor reports, so its form differs between vendors.

Time, money, and the one charged error

whisper-1 and Scribe answer in one call. AssemblyAI works asynchronously: the gateway uploads the file, submits the job and polls until it finishes, all inside your one request, which for a long recording can take minutes. The gateway waits up to 10 minutes, upload included. Set your client's timeout above that, as in the examples — the OpenAI SDKs default to exactly 10 minutes, and curl to none. If your client gives up first, the SDK counts it as a timeout and retries: a second job, charged again, while the first one still finishes and is charged too.

What is billed. Seconds of audio as the vendor reports them, rounded up (at least 1). The length is not known before the call, so the gateway reserves as if the file were compressed speech at 32 kbit/s (file bytes ÷ 4,000 = seconds), then settles to the real duration. That over-counts almost any real file — uncompressed 16 kHz WAV by 16× — so a 25 MB WAV holds about 6,550 seconds (about $0.38 at Universal-3.5 Pro) until it settles. With a tight per-request cap or a nearly spent budget, send compressed audio (mp3, opus) so the reservation fits.

Access and limits. As for speech: any AI key whose model allowlist includes the model, with requests per minute, concurrency, budgets and credit as usual. On a key that logs at full, the transcript and the form fields are kept, never the audio.

What comes back when it is refused

6.13 Sending mail — POST /v3/mail/send

The gateway speaks SendGrid's own path and wire format, so an existing project moves onto it by changing two lines and nothing else:

// TypeScript                                        # Python
sgMail.setApiKey(process.env.AI_GATEWAY_KEY);        sg = SendGridAPIClient(os.environ["AI_GATEWAY_KEY"])
sgMail.client.setDefaultRequest(                     sg.client.host = os.environ["AI_GATEWAY_URL"]
  "baseUrl", process.env.AI_GATEWAY_URL);

The body is forwarded to SendGrid verbatim. The gateway authenticates the key, applies its address rules, counts the recipients and attributes the send; it never rewrites your mail.

curl -sS $AI_GATEWAY_URL/v3/mail/send \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" -H "Content-Type: application/json" \
  -d '{"personalizations":[{"to":[{"email":"someone@example.com"}]}],
       "from":{"email":"noreply@yourdomain.com"},
       "subject":"Hello","content":[{"type":"text/plain","value":"Hi there"}]}'
# 202 Accepted, empty body — exactly as SendGrid answers

A mail key is a different kind of key. It is scoped to this endpoint and cannot call a model at all, and an AI key cannot send mail: either mistake is 403 service_not_allowed. Ask your admin for the kind you need.

Limits count recipients, not requests. One call can address up to 1,000 people, so a request-per-minute limit would not stop a blast. Your key carries ceilings per minute, per hour and per day, and a maximum per send; over any of them the send is refused with 429 recipient_limit_exceeded and nothing reaches SendGrid, so nothing counts against your account's reputation. The answer carries x-gw-recipients and x-ratelimit-remaining-recipients-minute / -hour / -day.

Every send is recorded in the key's send log with the sender, the recipients, the subject and the outcome — and, on a key that logs at full, the message itself. Refused sends are recorded too, with the recipients they would have reached.

7. What comes back in the headers

8. Errors and what to do about them

Errors come in the format of the endpoint you called — the OpenAI envelope on /v1/chat/completions, /v1/images/generations, /v1/embeddings and /v1/audio/*, the Anthropic envelope on /v1/messages — so the SDKs raise their normal typed exceptions. Every error carries a stable code; branch on that, not on the message.

{"error":{"message":"Monthly budget of $10.000000 for this key would be exceeded (remaining $0.002000, estimate $0.002014). Resets 2026-10-01T00:00:00.000Z.","type":"budget_error","code":"budget_exceeded",
          "request_id":"req_01…","budget":{"scope":"key","period":"monthly","cap_usd":10,"remaining_usd":0.002,"resets_at":"2026-10-01T00:00:00.000Z"}}}

9. Limits, budgets and money

Every gateway key carries limits set by the admin when it was created: requests per minute and per day, concurrent requests, daily / monthly / lifetime spending caps, a per-request cost cap, an allowed-model list, and address rules. They exist so that a leaked key or a runaway loop has a bounded blast radius. There is no tokens-per-minute limit: a cheap model returns a great many tokens for very little money, so the figure never bounded anything anyone cared about, and the x-ratelimit-*-tokens headers are no longer sent. You can read your own limits any time with GET /v1/key.

The gateway checks money before the vendor is called. It reserves the worst case — max_tokens multiplied by the output price plus the input — then settles to the real cost afterwards. This means a needlessly large max_tokens can be refused with 402 even though the actual answer would have been short. Ask for what you need.

The other endpoints reserve their own way: embeddings on the input alone, speech on the exact character count, transcription on the file's size (§6.10–6.12). A prompt past a model's long-context line is reserved and billed at the higher rate for the whole request (§4.3).

x-gw-billing tells you who pays: byok means the organisation's own vendor account is billed directly and the gateway only meters; prepaid means the cost is deducted from credit held with the gateway.

10. What is not supported

On /v1/chat/completions with Claude models

On /v1/chat/completions with OpenAI models

Refused with 400 unsupported_parameter because they change what OpenAI charges in ways the gateway cannot price yet — refusing is better than under-billing: web_search_options, prediction, audio / modalities: ["audio"], and service_tier other than auto / default.

On every endpoint

11. Getting and checking a key

Keys are created by your organisation's admin in the gateway console (Keys → New key). Tell them the project name, the models you need, a sensible budget and rate limit, and the addresses the project runs from. If your address changes, or you do not know it, ask them to tick "add the next new address automatically" and make one request within ten minutes: that address is added to the key's list, once, and the window closes. The secret is shown once — put it straight into your project's secret store as AI_GATEWAY_KEY.

Call GET /v1/key at startup: it fails fast if the key or URL is wrong, and it shows your limits, budgets, remaining spend and which vendor key your requests will route to. It never reveals which addresses are allowed, only how many there are.

{"key_id":"muhr4dre","name":"settlement-worker","status":"active","environment":"production",
 "routing":{"anthropic":{"vendor_key":"own:anthropic-production","billing":"byok",
                         "environment":"production","models":["anthropic/claude-opus-5"]}},
 "allowed_models":[],
 "rate_limits":{"rpm":120,"max_concurrency":8,"rpd":null,"rpm_per_ip":null},
 "budgets":[{"period":"monthly","cap_usd":10,"spent_usd":0.000411,"resets_at":"2026-10-01T00:00:00.000Z"}],
 "ip_mode":"allowlist","ip_allowlist_count":2,"ip_capture_open":false,"expires_at":null}

routing has an entry for each provider — anthropic, openai, xai, elevenlabs, assemblyai — saying which vendor key a request would use, who pays, which environment that key belongs to, and models: what that key allows, or "all". That list is the authoritative answer to "why was my model refused?" — a model outside it is 403 model_not_allowed naming the vendor key. A provider with no usable key shows "vendor_key": null and an error code: expect the same refusal from the endpoint.

In allowed_models, an entry ending /* — "openai/*" — means every model that provider's vendor key allows, whatever that becomes.

12. Telling your AI assistant

Most projects are written with an AI coding assistant. Two things make it integrate correctly the first time:

1. Give it docs/INTEGRATION.md — the machine-readable version of this guide, with exact request and response shapes.
2. Paste the block below into your project's CLAUDE.md (or AGENTS.md), so the rules apply to every future change without anyone remembering to mention them.

## AI calls go through A1 API Gateway
- All LLM calls use A1 API Gateway, never a vendor API directly. Never add a vendor API key.
- Base URL: `AI_GATEWAY_URL` env var. Key: `AI_GATEWAY_KEY` env var (`sk-gw-…`). Read both from the environment.
- OpenAI SDK: `baseURL = AI_GATEWAY_URL + "/v1"`. Anthropic SDK: `baseURL = AI_GATEWAY_URL` (no `/v1`).
- Model names are `provider/model`, e.g. `anthropic/claude-opus-5`. Prefer the alias the admin gave us if one exists.
- Always use `/v1/chat/completions` (OpenAI format). It supports PDFs/documents (`file` parts as base64 data URLs),
  images, tools, JSON output, reasoning, streaming, and prompt caching is automatic. `/v1/messages` only with admin approval.
- `GET /v1/models` lists the models we may use, each with a `capabilities` block (images, documents, tools, …) — check it
  rather than guessing. `POST /v1/messages/count_tokens` counts tokens for free before an expensive call.
- Put stable content first (system prompt, tools), the changing message last — that is what gets cached.
- Each model answers on one endpoint; the wrong one is `400 invalid_request` naming the right one.
- Image generation: `POST /v1/images/generations` with `gpt-image-2.5-flare` (or `-sunburst`) — only if our key allows it.
  No streaming, generation only, and quality drives the cost steeply (`low` → `max` is about 40x).
- Embeddings: `POST /v1/embeddings` with `openai/text-embedding-3-small` (or `-3-large`), OpenAI's body and reply unchanged.
- Speech: `POST /v1/audio/speech` returns raw audio bytes. ElevenLabs models need the `elevenlabs/` prefix and a voice
  name our organisation set up (or a 20-character ElevenLabs voice id); OpenAI names like `alloy` only work on `tts-1`.
- Transcription: `POST /v1/audio/transcriptions` (multipart, ≤ 25 MB) with `assemblyai/universal-3-5-pro`,
  `elevenlabs/scribe_v2` or `whisper-1`; all five response formats work. AssemblyAI can take up to 10 minutes: set the
  client timeout above that. A transcription 504 is charged and says `x-should-retry: false` — never retry it.
- Not available: Files API (`file_id`), batches, image editing, streaming audio, Responses API, web search.
- Retry only 429/502/503/504 with `retry-after` and backoff (never a transcription 504). 4xx other than 429 means fix the request or config.
- Every response has `x-gw-cost-usd` (exact cost) and `x-gw-request-id` (quote it in bug reports).
- Full reference: `docs/INTEGRATION.md` in the AIGateway repository.