Chat Completions

Create Chat Completion

post

Creates a chat completion for the provided messages. Supports streaming, function calling, vision, multimodal inputs, structured outputs (response_format), tool selection (tool_choice), semantic caching (cache + cache_key header), Anthropic prompt caching (cache_control on message content blocks), multi-model routing (models), request tagging (request_tags), free-tier requests (:free slug and fastrouter/free), and reasoning tokens for supported models (OpenAI o-series, Grok, Gemini thinking, Anthropic). Compatible with OpenAI SDK.

Free tier

Two ways to run a request on the free tier instead of billing credits:

:free slug — append :free to any opted-in model ID (e.g. openai/gpt-4o:free). The request is served from a per-(organization, model) daily quota instead of your credit balance. The suffix is stripped before routing, so the response model field returns the base model.
fastrouter/free — a virtual router that picks a random eligible free model for you. The pool is filtered by endpoint support, request capabilities (vision when image content is present, tool calling when tools are present, structured outputs when response_format is set), and remaining daily quota. fastrouter/free does not accept a trailing suffix — fastrouter/free:free and fastrouter/free:flex are rejected with 400.

The default quota is 10 requests per day per organization per model, reset at UTC midnight; individual models may be configured with a different limit. Free-tier requests never consume billing credits, even for paid organizations. Not every model is available on the free tier — :free is opt-in per model.

Free-tier error codes

Status

code

Meaning

400

free_slug_disabled

The model exists but is not enabled for :free.

400

no_free_model_available

fastrouter/free found no eligible free model for this request's requirements.

400

invalid_request_error

A trailing suffix was used on fastrouter/free (e.g. fastrouter/free:free).

404

model_not_found

The base model (after stripping :free) is not in the catalog.

429

free_quota_exhausted

Daily free-tier quota exhausted; includes quota_limit, quota_used, reset_at and a Retry-After header.

Authorizations

AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

modelstringRequired

Model ID in format 'provider/model'. Examples: openai/gpt-5.1, google/gemini-3-pro-preview, anthropic/claude-4.5-sonnet.

Supports shortcut suffixes, e.g. openai/gpt-4o:thinking (high reasoning effort) and openai/gpt-4o:free (free tier).

Free tier:

<provider>/<model>:free — serve this request from the daily free-tier quota (default 10 req/day/org/model, reset at UTC midnight) instead of billing credits. Only models opted in to :free are accepted: an unknown base model returns 404 model_not_found, an opted-out model returns 400 free_slug_disabled, and an exhausted quota returns 429 free_quota_exhausted. The suffix is stripped before routing, so the response model is the base model.
fastrouter/free — virtual free-tier router: FastRouter picks a random eligible free model that supports this endpoint and the request's capabilities (vision, tools, response_format) and still has quota left. Returns 400 no_free_model_available when nothing qualifies. It does not accept a trailing suffix (fastrouter/free:free, fastrouter/free:flex → 400).

Example: anthropic/claude-4.5-sonnet

modelsstring[]Optional

Optional list of model IDs for multi-model routing. FastRouter can route across these models in order. Supports shortcut syntax (e.g. openai/gpt-4o:thinking to enable high reasoning effort, openai/gpt-4o:free to serve a fallback entry from the free-tier quota). Can be used alongside a single model.

Example: ["openai/gpt-4o","anthropic/claude-4.5-sonnet"]

request_tagsstring[]Optional

Optional tags to attach to the request for logging, analytics, and filtering.

Example: ["production","feature-chat"]

temperaturenumber · max: 2Optional

Controls randomness in responses. Lower values (0-0.7) make output more focused and deterministic. Higher values (0.8-2) make output more creative and random.

Default: 1Example: 0.7

max_tokensinteger · min: 1Optional

Maximum number of tokens to generate in the completion. Limits the length of the response.

Example: 1000

top_pnumber · max: 1Optional

Nucleus sampling parameter. Alternative to temperature. Lower values make output more focused.

Default: 1Example: 0.9

frequency_penaltynumber · min: -2 · max: 2Optional

Penalizes repeated tokens based on frequency. Positive values reduce repetition.

Default: 0Example: 0

presence_penaltynumber · min: -2 · max: 2Optional

Penalizes tokens that have appeared. Positive values encourage new topics.

Default: 0Example: 0

streambooleanOptional

Enable streaming responses for real-time output. When true, responses are sent as Server-Sent Events (SSE).

Default: falseExample: true

stopone ofOptional

Stop sequences where the model will stop generating. Can be a string or array of strings.

Example: ["\\n","END"]

stringOptional

string[]Optional

toolsarrayOptional

Array of tool/function definitions

tool_choiceone ofOptional

Controls which tool (if any) the model calls. Accepts a string (auto, none, required) or an object to force a specific tool.

Example: auto

string · enumOptional

Controls tool usage: auto (model decides), none (disable tools), or required (force a tool call).

Possible values:

aspectRatiostring · enumOptional

Image aspect ratio for Nano Banana (google/gemini-2.5-flash-image). Supported ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

Example: 3:2Possible values:

promptstringOptional

Natural-language description for audio generation (ace-step/prompt-to-audio). Describe the audio, music, or ambient sound to generate.

Example: A lofi hiphop song with a chill vibe about a sunny day on the boardwalk.

durationinteger · min: 1Optional

Duration of the audio clip in seconds for text-to-audio generation (ace-step/prompt-to-audio). Optional parameter.

Example: 5

Responses

200

Successful chat completion response

application/json

idstringOptional

Unique identifier for the completion

Example: chatcmpl-123

objectstringOptional

Object type, always 'chat.completion' or 'chat.completion.chunk' for streaming

Example: chat.completion

modelstringOptional

The bare model name used for the completion (without the provider prefix). The routed provider is returned separately in usage.provider.

Example: gpt-5-mini

service_tierstringOptional

The service tier used to process the request (when applicable).

Example: default

guardrailsobject · nullableOptional

Guardrail evaluation results attached by FastRouter, when guardrails are enabled.

citationsobject[] · nullableOptional

Citations/sources returned by the model (e.g. for web-search-enabled models). null when there are none.

400

Bad Request - Invalid parameters.

Free-tier cases:

free_slug_disabled — :free was used on a model that is not enabled for the free tier.
no_free_model_available — fastrouter/free found no eligible free model for this request's requirements.
invalid_request_error — a trailing suffix was used on fastrouter/free.

application/json

401

Invalid Credentials - Your API key is invalid, missing, or disabled. Check your credentials.

Note: the 401 error body uses code, message, param, and type (there is no status field), and type is invalid_request_error.

application/json

404

Model not found. Returned when the base model — after stripping a :free suffix — is not in the catalog.

application/json

429

Rate Limited - You have exceeded your request limits (TPM/RPM), or the daily free-tier quota for a :free / fastrouter/free request is exhausted (free_quota_exhausted). Free-tier responses include a Retry-After header with the seconds until the quota resets, plus quota_limit, quota_used, and reset_at in the body.

application/json

500

Internal Server Error

post/api/v1/chat/completions

POST /api/v1/chat/completions HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "model": "openai/gpt-5.1",
  "messages": [
    {
      "role": "user",
      "content": "What is the meaning of life?"
    }
  ]
}

{
  "id": "fr_441cb234-dd59-4ace-96c0-53782b9dfb38",
  "object": "chat.completion",
  "model": "gpt-5-mini",
  "service_tier": "default",
  "guardrails": {},
  "citations": null,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi there, friend.",
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 270,
    "total_tokens": 283,
    "completion_tokens_details": {
      "reasoning_tokens": 256
    },
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "cost": 0.00054325,
    "chat_id": "fr_441cb234-dd59-4ace-96c0-53782b9dfb38",
    "provider": "openai"
  }
}

PreviousZero Data Retention

NextResponses

Last updated 4 months ago