Chat Completions

Replace <BASE_URL> using values from Endpoints.

Create a model response for a multi-turn conversation.

POST <BASE_URL>/v1/chat/completions

Protocol note: OpenAI-shaped entry for any sellable catalog model. Client shape and upstream protocol may differ; the gateway translates (e.g. anthropic/* → Anthropic Messages). For Claude images use /v1/messages.

Authentication

Required: Authorization: Bearer <API_KEY>

Request headers

Header	Required	Description
`Authorization`	Yes	Bearer API key
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Prevents duplicate calls within 24h
`Accept-Language` / `X-Locale`	No	Affects localized error messages where applicable

Request body

SupaNexus accepts the OpenAI Chat Completions JSON shape and reads model and stream; other fields follow OpenAI-compatible behavior. For multimodal input (image_url, and video_url as public URLs only), see Parameters → Multimodal input.

{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}

Field	Required	Description
`model`	Yes	Model id from `GET /v1/models` (e.g. `deepseek/deepseek-chat`)
`messages`	Yes	Chat message array (OpenAI format)
`stream`	No	`true` for SSE streaming — see Streaming

Non-streaming response

Returns OpenAI-compatible JSON. Example shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2000,
    "completion_tokens": 300,
    "total_tokens": 2300,
    "prompt_tokens_details": {
      "cached_tokens": 1500
    }
  }
}

prompt_tokens_details.cached_tokens (OpenAI) counts input tokens served from Prompt Cache. SupaNexus uses this with cached input pricing when configured; otherwise all input tokens bill at the input rate.

Usage and Prompt Cache billing

SupaNexus does not run Prompt Cache but reads cache fields from the response usage for billing:

Provider	Typical field
OpenAI	`usage.prompt_tokens_details.cached_tokens`
Anthropic	`usage.cache_read_input_tokens`

Billing (simplified):

charge ≈ (prompt_tokens − cached_hit) × input_rate
       + cached_hit × cached_input_rate
       + completion_tokens × output_rate

See the Models marketplace for rates — Model pricing. Server-side usage records may include cached_input_tokens.

Response headers (SupaNexus)

Header	Description
`X-SNX-Trace-ID`	Unique request id for support
`X-SNX-Model`	Model id used for this request
`X-SNX-Provider`	Vendor identifier for the inference provider

Idempotency

Send Idempotency-Key: <unique-string> to deduplicate chat requests within 24 hours per API key. If the same key was already processed:

HTTP 409
error.code: duplicate_request

If Idempotency-Key is omitted, SupaNexus may fall back to X-SNX-Trace-ID.

Routing

SupaNexus selects an available service for your model id. If the request cannot be completed, you may receive 502 or 503.

Data and privacy

SupaNexus does not store conversation history across requests — callers assemble messages[] on every call.

Handling	Description
Request body	SupaNexus does not persist prompt/completion text by default
Usage records	Call time, model, token counts, and billing-related metadata
Support	Provide `X-SNX-Trace-ID` when contacting support

Chat history in the developer console Text chat playground lives only in the current browser session; SupaNexus does not restore it from the server after refresh or close.

See Privacy Policy and Terms of Service.

Common errors

HTTP	Meaning
400	Missing `model`, invalid JSON, or illegal `video_url` (not public http(s))
401	Authentication failed
413	Request body exceeds the default 64 MB
402	Insufficient account balance (`error.code=402`)
404	Unknown or unavailable model
408	Request timeout (default 120s)
409	Idempotency conflict
429	Usage quota exceeded
502	Service temporarily unavailable
503	Service temporarily unavailable

See Errors for full reference.