API reference

The gateway implements the public OpenAI and Anthropic HTTP APIs, so official SDKs and most third-party clients work unchanged. This page lists what is supported, the fields that matter, and where behaviour differs from calling a provider directly.

Base URLs#

All endpoints use HTTPS, accept and return JSON (UTF-8), and stream with server-sent events when stream is true.

Authentication#

Create keys under API keys in the console. A key works for both formats; send it in whichever header your client uses:

Endpoints#

• POST/v1/chat/completionsChat with any model. The most widely supported endpoint. (OpenAI format)
• POST/v1/responsesOpenAI Responses API, used by Codex CLI and newer OpenAI SDK features. (OpenAI format)
• POST/v1/messagesAnthropic Messages API, used by Claude Code and the Anthropic SDKs. (Anthropic format)
• GET/v1/modelsList the model ids your key can call. (OpenAI format)
• POST/v1/embeddingsVector embeddings, when an embedding model is enabled. (OpenAI format)

Chat completions#

The universal endpoint. Every model in the catalogue that supports the OpenAI format can be called here, including Claude models, which the gateway translates for you.

Request body#

modelstringrequired

Exact model id, for example gpt-5.6-terra. See models by format.

messagesarrayrequired

Conversation so far. Each item has a role (system, user, assistant, tool) and content.

streamboolean

Send tokens as server-sent events. Recommended for long outputs.

stream_optionsobject

{"include_usage": true} adds a final chunk with token usage.

max_tokens / max_completion_tokensinteger

Upper bound on generated tokens. Reasoning models prefer max_completion_tokens.

temperature, top_pnumber

Sampling controls. Some reasoning models ignore or reject them.

tools, tool_choicearray, string | object

Function calling. See tool calling.

response_formatobject

Ask for JSON output ({"type": "json_object"} or a JSON schema) on models that support it. Not forwarded to Claude models; see structured output.

stopstring | array

Stop generating when one of these strings appears.

Other standard OpenAI parameters are forwarded when the target model supports them. Unsupported parameters are either ignored or rejected with a 400 by the upstream model. The full field list, and what changes for Claude models, is on Chat completions.

curl https://api.oneaiapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $RELAYKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me three names for a CLI tool."}
    ],
    "max_tokens": 200
  }'

Response#

{
  "id": "chatcmpl-9f2c…",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. shipit\n2. tern\n3. relay"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 14,
    "total_tokens": 41
  }
}

finish_reason is stop for a natural end, length when max_tokens was hit, andtool_calls when the model wants you to run a tool.

Responses API#

OpenAI's newer request shape (input instead of messages, typed output items). Codex CLI uses it by default. It is fully supported for GPT-family models. Claude models are translated, but the stateful fields (previous_response_id, conversation) are rejected; for other families use chat completions. Responses are not stored, so there is no GET or DELETE on /v1/responses/{id}. See Responses API.

curl https://api.oneaiapikey.com/v1/responses \
  -H "Authorization: Bearer $RELAYKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Summarise the Unix philosophy in one line."
  }'

resp = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarise the Unix philosophy in one line.",
)
print(resp.output_text)

const resp = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Summarise the Unix philosophy in one line.",
});
console.log(resp.output_text);

Messages (Anthropic)#

The native Anthropic format, used by Claude Code and the Anthropic SDKs. Use it for models marked Anthropic format. Prefer it for Claude when you need Anthropic-specific features such as prompt caching controls, extended thinking blocks or exact stop_reason values.

Required fields: model, max_tokens and messages. Optional: system, stream, temperature, stop_sequences, tools, tool_choice,thinking, output_config. anthropic-beta headers are forwarded to the upstream.anthropic-version defaults to 2023-06-01 when you leave it out. Token counting (/v1/messages/count_tokens) is not available. See Anthropic Messages.

curl https://api.oneaiapikey.com/v1/messages \
  -H "x-api-key: $RELAYKIT_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "You are a senior code reviewer.",
    "messages": [{"role": "user", "content": "Review: def add(a, b): return a - b"}]
  }'

import os
import anthropic

client = anthropic.Anthropic(base_url="https://api.oneaiapikey.com", api_key=os.environ["RELAYKIT_API_KEY"])

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system="You are a senior code reviewer.",
    messages=[{"role": "user", "content": "Review: def add(a, b): return a - b"}],
)
print(msg.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ baseURL: "https://api.oneaiapikey.com", apiKey: process.env.RELAYKIT_API_KEY });

const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  system: "You are a senior code reviewer.",
  messages: [{ role: "user", content: "Review: def add(a, b): return a - b" }],
});
console.log(msg.content[0].text);

{
  "id": "msg_01H…",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Bug: the function subtracts instead of adding. Use `return a + b`."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 31,
    "output_tokens": 19,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

List models#

Returns the model ids your key is allowed to call. If a key has an allowed-model list, only those models appear. Sent withx-api-key and anthropic-version headers (as the Anthropic SDKs do), the same route answers in Anthropic's list format.

curl https://api.oneaiapikey.com/v1/models \
  -H "Authorization: Bearer $RELAYKIT_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "claude-opus-5-5",
      "object": "model"
    },
    {
      "id": "claude-sonnet-5",
      "object": "model"
    },
    {
      "id": "claude-haiku-4-5",
      "object": "model"
    }
  ]
}

Embeddings#

Accepts the standard OpenAI embeddings request. It only works with embedding models; chat models return an error here. Check GET /v1/models to see whether an embedding model is enabled for your account before building on it.

curl https://api.oneaiapikey.com/v1/embeddings \
  -H "Authorization: Bearer $RELAYKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<embedding-model-id>",
    "input": ["first document", "second document"]
  }'

Streaming (SSE)#

Set "stream": true and read the response as text/event-stream. Official SDKs handle parsing for you. If you parse by hand, split on blank lines, read the data: field, and ignore event types you do not recognise (for example keep-alive ping events).

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hel"}}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"lo"}}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2,"total_tokens":14}}

data: [DONE]

event: message_start
data: {"type":"message_start","message":{"id":"msg_1","role":"assistant","content":[],"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":2}}

event: message_stop
data: {"type":"message_stop"}

• OpenAI format ends with data: [DONE]. Add "stream_options": {"include_usage": true} to receive token usage in the last chunk.
• Anthropic format ends with message_stop; token usage arrives in message_start and message_delta.
• An error that happens mid-stream arrives as an error event; treat the partial output as incomplete.

Tool calling#

Function and tool calling work on models that support them upstream (current Claude and GPT models do). Send tool definitions in the format of the endpoint you are calling; the gateway translates between formats when a Claude model is called through the OpenAI endpoint.

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Pune?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Pune?"
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  ]
}

1. The model replies with tool_calls (OpenAI) or a tool_use content block (Anthropic).
2. Your code runs the tool and sends the result back: a tool role message with the matching tool_call_id, or a tool_result block with the matching tool_use_id.
3. The model continues with the result. Each round trip is a separate, separately billed request.

Usage & billing#

Every successful response reports the tokens you were charged for. Your prepaid balance is reduced by input tokens × input rate + output tokens × output rate, using the per-million-token rates on the models page. Cached input tokens are billed at the lower cached rate where a model has one.

Worked example. A Claude Sonnet 5.5 request with 12,000 input tokens and1,500 output tokens costs $0.0264 for input ($2.20 per 1M) plus$0.0165 for output ($11 per 1M), so $0.0429 in total.

The console shows your live balance and a per-request usage log with model, tokens and cost, so you can reconcile any charge. Requests rejected by the gateway (invalid key, no balance, unknown model) are not charged.

Rate limits & timeouts#

• Gateway limits. There is no per-account request rate limit on /v1/*. Per-model limits are off by default; when one applies, the 429 message says "Rate limit reached: at most N requests per M minutes".
• Upstream limits. Providers throttle a model under heavy load. These surface as 429 or 503 and are safe to retry with backoff. The gateway does not retry for you.
• Streaming timeout. A stream is closed after 300 seconds without data from the model.
• Non-streaming requests. The gateway does not cut them off, but your client or a proxy may. Use stream: true for long outputs and reasoning models, and set your HTTP client timeout to several minutes.
• Request size. Request bodies are limited to 128 MB (413 above that).

Details and retry code: Rate limits and retries. Planning sustained high volume (batch jobs, many parallel agents)? Email support@relaykit.dev before launch so we can confirm capacity.

Errors#

Errors use the OpenAI envelope, {"error": {"message", "type", "code"}}, with an HTTP status that tells you what to do: 400 fix the request, 401 check the key, 403 balance, key limits or model access, 404 unknown model or route, 429 and 5xx retry with backoff. Errors from Claude models on /v1/messages use Anthropic's {"type": "error", "error": {...}} shape. Every response carries an X-Request-Id header to quote to support. See Errors for every message.

Not available#

These parts of the OpenAI and Anthropic APIs are not offered. Requests to them fail with 404 or 501:

• Files, fine-tuning, image variations, Assistants, Threads and Batch (OpenAI).
• Stored responses: GET / DELETE /v1/responses/{id}.
• Token counting, Message Batches and the Files API (Anthropic).

Models by format#

Exact ids to send in the model field, and which endpoint family each one accepts. Rates are USD per 1M tokens.