Chat completions

Generate a model response for a conversation. This endpoint follows the OpenAI Chat Completions format; see Streaming and Tool calling & JSON for the guides.

Request body#

modelstringrequired

A Claud model slug or alias, for example claud-5.1. See Models.

messagesarrayrequired

The conversation so far. Each message has a role (system, developer, user, assistant or tool) and content, which is a string, null (assistant tool-call turns) or an array of text / image_url parts. Assistant messages may carry tool_calls and reasoning_content; tool messages must carry tool_call_id. developer is accepted as an alias of system.

max_tokensinteger

Upper bound on generated tokens (including reasoning tokens). Defaults to the model's maximum output. max_completion_tokens is accepted as a synonym and takes precedence.

temperaturenumberdefault: model default

Sampling temperature between 0 and 2.

top_pnumber

Nucleus sampling threshold in (0, 1].

frequency_penaltynumber

Between -2 and 2.

presence_penaltynumber

Between -2 and 2.

stopstring | string[]

Up to 16 sequences at which generation halts.

streambooleandefault: false

Stream the response as server-sent events. See Streaming.

stream_optionsobject

{ include_usage: boolean }. Usage chunks are sent by default; set false to suppress them.

response_formatobject

{ type: "text" | "json_object" | "json_schema" }. json_schema is treated as json_object; include the schema in your prompt. See JSON output.

toolsarray

Function definitions: { type: "function", function: { name, description?, parameters? } }. Up to 128.

tool_choicestring | object

none, auto, required, or { type: "function", function: { name } }.

reasoning_effortstring

none, minimal, low, medium, high, xhigh or max. Controls thinking depth on reasoning-capable models; ignored otherwise. minimal maps to low; medium/xhigh map to high.

thinkingobject

{ type: "enabled" | "disabled" }. Alternative to reasoning_effort.

userstring

Opaque end-user identifier (max 256 chars) recorded on usage records for your own attribution. Never used for billing.

nintegerdefault: 1

Only 1 is supported.

Unknown fields such as metadata, store, seed and logprobs are accepted and ignored so existing OpenAI-format code does not need to be edited.

Response#

Returns a chat.completion object. The usage block includes Claud's billing fields alongside the standard token counts.

{
  "id": "chatcmpl-01J9X3Q5K7M2N8P4R6T0V2W4Y6",
  "object": "chat.completion",
  "created": 1789494225,
  "model": "claud-5.1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Rivers carve the stone..." },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 18,
    "claud_tokens_debited": "102",
    "claud_cost_usd": "0.000204"
  },
  "system_fingerprint": "fp_claud"
}

choices[].message.contentstring | null

The generated text, or null when the model only returned tool calls.

choices[].message.reasoning_contentstring

Present on reasoning models: the model's thinking. Pass it back on the next turn during tool use.

choices[].message.tool_callsarray

Function calls the model wants you to run: { id, type: "function", function: { name, arguments } } where arguments is a JSON string.

choices[].finish_reasonstring

stop, length, tool_calls, content_filter or insufficient_system_resource.

usage.claud_tokens_debitedstring

Claud tokens charged for this request, as a decimal string.

usage.claud_cost_usdstring

The same charge expressed in USD.

Response headers#

Examples#

curl https://api.claudkey.com/v1/chat/completions \
  -H "Authorization: Bearer $CLAUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claud-5.1",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Write a haiku about rivers."}
    ],
    "max_tokens": 200
  }'

Errors#

See Errors for the full list.