API Reference

Authentication vs. entitlement failures

These fail for different reasons and need different fixes. A retry never helps with either.

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Model 'altllm-flex-gpt-5.6' requires Flex tier or higher. Your current tier: Free. Upgrade at https://platform.altllm.ai/billing/upgrade",
    "type": "tier_upgrade_required",
    "code": "forbidden",
    "current_tier": "free",
    "required_tier": "flex",
    "model": "altllm-flex-gpt-5.6",
    "upgrade_url": "https://platform.altllm.ai/billing/upgrade"
  }
}

Business Flex SKUs are track-locked. A Personal account does not merely lack permission — the models are filtered out of GET /v1/models entirely, and GET /v1/models/{model_id} returns 404 rather than revealing that they exist.

Endpoints AltLLM does not implement

An authenticated request to any of these returns 404 with type: "not_found" and code: "route_not_found". They fail immediately rather than timing out or half-working.

Request fields

Every field the gateway reads, plus the OpenAI fields it forwards untouched. The Support column is the one that matters: AltLLM never rejects a request because a provider dislikes a sampling parameter — it drops the parameter instead, so one request body works across the whole catalog.

Minimal request

curl https://api.altllm.ai/v1/chat/completions \
  -H "Authorization: Bearer $ALTLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "altllm-standard",
    "messages": [
      {"role": "system", "content": "You are a concise crypto research assistant."},
      {"role": "user", "content": "Summarize what EIP-4844 changed for rollup costs."}
    ],
    "max_tokens": 500
  }'

Roles

Message schema

{
  "role": "system" | "user" | "assistant" | "tool",

  // Required unless the assistant message carries tool_calls.
  // String, or an array of content parts (see below).
  "content": string | ContentPart[] | null,

  // Assistant messages only. Present when the model requested a tool.
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": { "name": "get_token_price", "arguments": "{\"symbol\":\"ETH\"}" }
    }
  ],

  // Tool messages only. Must match the id of the call being answered.
  "tool_call_id": "call_abc123",

  // Optional label. Not interpreted by the gateway.
  "name": "string"
}

Ordering rules

• A system message, if present, comes first. On catalog models AltLLM prepends its own identity prompt to yours; on altllm-native-* and altllm-flex-* models your system prompt is sent unmodified.
• Every tool message must follow the assistant message whose tool_calls contains its tool_call_id.
• An assistant message with tool_calls needs one tool message per call before the next completion, or the provider rejects the conversation.
• Total input must fit the model’s context window. AltLLM does not truncate for you — an oversized request fails upstream.

Content parts

{
  "model": "altllm-standard",
  "messages": [
    {"role": "system", "content": "You are a concise crypto research assistant."},
    {"role": "user", "content": [
      {"type": "text", "text": "Here is the contract ABI:"},
      {"type": "text", "text": "[{\"name\":\"transfer\",\"type\":\"function\"}]"}
    ]},
    {"role": "assistant", "content": "This ABI exposes a single transfer function."},
    {"role": "user", "content": "What access control should it have?"}
  ]
}

Event ordering

• The first chunk carries delta.role. Later chunks carry delta.content fragments.
• Exactly one chunk carries a non-null finish_reason with an empty delta.
• The stream always ends with the literal line data: [DONE]. Stop reading there; do not attempt to parse it as JSON.
• id, created, and model stay constant across every chunk of one completion.

Errors after the stream starts

Once headers are sent the status is already 200 and cannot be changed. If the provider connection drops mid-generation, AltLLM emits an error event in the stream and closes it. Treat any stream that ends without [DONE] as incomplete.

data: {"id":"chatcmpl-9f2b1c4a8e7d","object":"chat.completion.chunk","created":1755500000,"model":"altllm-standard","choices":[{"index":0,"delta":{"content":"Arbitrum"},"finish_reason":null}]}

data: {"error":{"message":"The model stream ended before completion. Please retry the request.","type":"upstream_stream_error","code":"stream_interrupted"}}

This is retryable. A Chat stream that uses AltLLM server-side tools is charged only after a valid terminal event and final usage block, so an interrupted or malformed tool stream creates no charge. Other streaming paths settle only from provider-reported usage; use the Portal transaction record as the billing source of truth rather than partial output.

Streaming with server-side tools

When AltLLM’s built-in crypto tools are active, the gateway resolves tool calls before opening the stream to you. Time to first token is therefore longer on tool-using turns, and you never see the intermediate tool traffic — only the final answer streams.

Full custom-tool lifecycle

Five steps. The conversation grows by two messages per tool round trip, and you resend the whole thing each time — the API is stateless.

{
  "model": "altllm-standard",
  "messages": [
    {"role": "user", "content": "What is the portfolio value of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_portfolio",
      "description": "Return the total USD value of a wallet's holdings.",
      "parameters": {
        "type": "object",
        "properties": {
          "wallet_address": {"type": "string", "description": "0x-prefixed EVM address"}
        },
        "required": ["wallet_address"],
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": "auto"
}

{
  "id": "chatcmpl-9f2b1c4a8e7d",
  "object": "chat.completion",
  "created": 1755500000,
  "model": "altllm-standard",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_7d3f9a1b",
        "type": "function",
        "function": {
          "name": "get_portfolio",
          "arguments": "{\"wallet_address\":\"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {"prompt_tokens": 91, "completion_tokens": 33, "total_tokens": 124}
}

3. Your application parses function.arguments — always a JSON string, never an object — and runs the tool.

{
  "model": "altllm-standard",
  "messages": [
    {"role": "user", "content": "What is the portfolio value of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_7d3f9a1b",
        "type": "function",
        "function": {
          "name": "get_portfolio",
          "arguments": "{\"wallet_address\":\"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\"}"
        }
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_7d3f9a1b",
      "content": "{\"total_usd\": 1284300.55, \"chain\": \"ethereum\"}"
    }
  ],
  "tools": [{"type": "function", "function": {"name": "get_portfolio", "description": "Return the total USD value of a wallet's holdings.", "parameters": {"type": "object", "properties": {"wallet_address": {"type": "string"}}, "required": ["wallet_address"]}}}]
}

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "That wallet holds about $1,284,300 on Ethereum mainnet.",
      "tool_calls": null
    },
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 148, "completion_tokens": 21, "total_tokens": 169}
}

Edge cases

• Keep resending tools on every follow-up request. Omitting it after a tool result leaves the model unable to reference the definition.
• Parallel calls: a single assistant message can contain several entries in tool_calls. Answer every one with its own tool message before the next request, matching each tool_call_id.
• Tool failures: return the error as the tool message content — for example {"error": "address not found"}. Do not omit the message; the conversation becomes invalid without it.
• Streaming tool calls: arguments arrive fragmented across delta.tool_calls[].function.arguments chunks. Concatenate by index before parsing — an individual fragment is not valid JSON.
• Name collisions: your tool names take precedence, because built-in tools are not injected once you send any tool.
• Tool budgets: providers cap how many tool definitions they accept per request — roughly 50 for Claude models and around 100 for others. Keep your set small.

Access and entitlement

• Each model has a minimum plan tier, configured in the Portal. Requesting one above your plan returns 403 tier_upgrade_required, naming the required_tier.
• Flex SKUs are track-locked and fail closed: an account without the Business track cannot reach them under any tier.
• Models an administrator has disabled disappear from discovery for everyone.
• Because entitlement is per account, do not hard-code a model list. Call GET /v1/models at startup and select from what comes back.

Capabilities at a glance

• Streaming: every published model.
• Function calling: every published model.
• Prompt caching: altllm-standard, altllm-native-fast, altllm-native-flash, altllm-native-light, altllm-native-standard, altllm-native-promax, altllm-basic, altllm-pro, altllm-light-coding, altllm-pro-coding, altllm-max-coding, altllm-flex-gpt-5.6, altllm-flex-gemini-3.6. Cached input bills at the reduced rate shown in each model’s pricing.input_cache_read.
• Reasoning: models listing reasoning in supported_features generate hidden reasoning tokens that count as output tokens and are billed as such.
• Vision: not reachable — see content parts.

Rate-limit headers

How usage is billed

• Cost is prompt_tokens × input rate + completion_tokens × output rate, at the per-model rates in the tables above, deducted from your credit balance.
• Cached input is billed at input_cache_read instead of the standard input rate, and is subtracted from the fresh-input count rather than charged twice.
• Reasoning tokens are part of completion_tokens and are billed at the output rate even though you never see them.
• Server-side tool execution adds tokens to prompt_tokens: tool schemas and results re-enter the model as input. A tool-using turn costs more than the same question without tools.
• Interrupted Chat tool streams create no charge unless the gateway receives both a valid terminal event and final usage. Other stream modes settle from completed provider-reported usage.
• Credits expire. Check X-Credits-Expire-At, and see the pricing page for cycle behavior.

Retry policy

• 429: honor Retry-After when present; otherwise back off exponentially from one second with jitter.
• 500, 502, 503: retry up to three times with exponential backoff; honor Retry-After when present.
• Interrupted streams: retry the whole request. Partial output is not resumable.
• 400, 401, 402, 403, 404: never retry unchanged. Fix the request, the key, the balance, or the plan first.

Reporting a problem

Include the X-Request-ID response header, the model ID, the UTC timestamp, and the full error body. That header is the correlation key in AltLLM’s logs — a report without it is much slower to investigate.