POST/v1/chat/completions

Chat Completions

Creates a chat completion for the given messages. Streaming supported via SSE. Pass model as an array for cost-aware fallback (e.g. ["fc:openai/gpt-4o-mini", "fc:openai/gpt-4o"]) — Ringside walks the chain on 5xx / schema-validation failure and surfaces the winner via X-Ringside-Model-Used.

Request

HTTP: POST
URL: /v1/chat/completions
Auth: api_key, client_token

Try it

curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "FC-Customer: cust_42" \
  -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

# Cost-aware fallback: try cheap first, escalate on failure
curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer $FC_API_KEY" \
  -d '{
    "model": ["fc:openai/gpt-4o-mini", "fc:openai/gpt-4o"],
    "messages": [{"role":"user","content":"Hello"}]
  }'
# Response headers indicate which model served:
#   X-Ringside-Model-Used: fc:openai/gpt-4o
#   X-Ringside-Models-Tried: fc:openai/gpt-4o-mini,fc:openai/gpt-4o
#   X-Ringside-Fallback-Triggered: true

Parameters

Name	Type	Description
model*	string \| string[]	Prefixed model ref (e.g. "fc:openai/gpt-4o-mini"). Must start with fc:, slot:, or match: — a bare name like "gpt-4o" returns 400 invalid_model_ref. Pass an array to enable a cost-aware cascade — first model is tried first, escalates to the next on 5xx / upstream_unavailable / response_schema_validation_failed. Stream + array is rejected with 400 fallback_with_stream_unsupported.
messages*	array	List of message objects with role + content.
stream	boolean	When true, response is a stream of SSE chunks. Cannot be combined with model:[] cascade.
temperature	number	0-2. Higher = more random.
max_tokens	integer	Cap output tokens.
tools	array	Function tool definitions (OpenAI-compatible).
response_format	object	{ type: "json_schema", json_schema: {...} } enforces strict JSON output across all 19 providers — non-native models get a runtime ajv loop with up to 2 re-prompts; persistent failure → 422 response_schema_validation_failed.
FC-Customer	header	Optional. Attribute the call to an FC Customer for budget + reporting.

Response fields

Name	Type	Description
id	string	Completion ID.
object	string	Always "chat.completion".
choices	array	Generated choices.
usage	object	Token counts for input + output.

Errors

401invalid_api_key, Missing or revoked key.
402budget_exceeded, Customer budget exhausted.
429rate_limited, Per-IP, per-token, per-dev or per-customer ceiling hit.
422response_schema_validation_failed, Model output did not match response_format.json_schema after 2 re-prompts.
400fallback_with_stream_unsupported, model:[...] cascade requested with stream:true. Pick one or the other.
400fallback_with_idempotency_unsupported, model:[...] cascade requested with Idempotency-Key. Pick one or the other.
503upstream_unavailable, Provider returned an error and no fallback succeeded.

See the full error reference.

Examples

streaming-chat-completion →frontend-chatbot-client-tokens →migrating-from-openai-in-3-lines →