API reference/Endpoints & examples/Chat Completions

Chat Completions

An OpenAI Chat Completions compatible endpoint. The OpenAI SDKs, most chat clients, and agent frameworks connect directly, and non-OpenAI models such as Claude, Gemini, and DeepSeek can be called in this format too.

POSThttps://api.wokey.ai/v1/chat/completions· OpenAI Chat Completions compatible

On this pageexpand_more

Example
Headers
Request parameters
How Wokey handles it
Response
Streaming
Error format

Examplelink

Set the base URL to https://api.wokey.ai/v1; the OpenAI SDKs need no other change. /chat/completions without /v1 works too.

curl https://api.wokey.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Hello" }
    ],
    "max_tokens": 1024
  }'

Headerslink

Header	Value	Description
`Authorization`Required	Bearer YOUR_API_KEY	Your Wokey API key. x-api-key: YOUR_API_KEY works as well.
`Content-Type`Required	application/json	The request body is JSON.
`X-End-User-Id`	string	Optional. Your end user's ID, 1–128 visible ASCII characters. With it, restrictions triggered by repeated violations apply only to that end user, not your whole account.

Request parameterslink

The parameters below are read by the gateway or change its behavior. Other OpenAI parameters are forwarded as far as the chosen model's upstream supports them.

Parameter	Type	Description
`model`Required	string	A model ID that exactly matches one in the model list. A wrong ID returns 404 model_not_found, and the message suggests the closest correct ID.
`messages`Required	array	The conversation, at least one message. role is system, developer, user, assistant, or tool; content is a string or an array of text and image_url parts.
`max_tokens`	integer	Output token limit, a positive integer; max_completion_tokens is accepted too. Claude models default to 4096 when it is omitted; GPT models ignore it and let the upstream decide.
`stream`	boolean	When true, the response streams as SSE. See Streaming below.
`tools`	array	Function tool definitions. Every model uses the same format and the gateway converts it for the upstream. tool_choice and parallel_tool_calls are supported too.
`reasoning_effort`	string	Reasoning effort for GPT and other reasoning models, such as low, medium, or high; GPT defaults to medium. It has no effect on Claude models called through this endpoint, which think at their default effort; use the Messages endpoint to control Claude's thinking.
`response_format`	object	Structured output. It only takes effect on models forwarded in Chat format as-is, such as DeepSeek, GLM, and Kimi. GPT and Claude models ignore it; for structured output use text.format on Responses or the Messages endpoint.
`stop`	string \| array	Stop sequences. Claude models receive them as stop_sequences; GPT models do not support them and ignore them.
`temperature`	number	Current reasoning models set their own sampling, so the gateway does not forward temperature. Only Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 (range 0–1) and Grok accept it. The same applies to top_p.
`prompt_cache_key`	string	Cache key for GPT models, up to 64 characters. When it is omitted, the gateway derives one from the start of the conversation so later turns still hit the cache.
`cache_control`	object	Claude models only, at the top level of the body. The gateway turns on 5-minute prompt caching for Claude requests by default; send {"type": "ephemeral", "ttl": "1h"} for a 1-hour cache, whose writes cost more.
`provider`	object	A Wokey extension that picks or excludes vendors. It is used for routing only and is not forwarded upstream.

How Wokey handles itlink

What the gateway does before and after forwarding, and where it differs from calling the official API directly.

Every text model can be called in this format. The gateway picks the upstream protocol by model and converts the request and response, so calling Claude or Gemini needs no other SDK.
Image and video models cannot be called here; they return 404 with a message pointing to /v1/images/generations or /v1/videos.
Send images as image_url parts, either https links or base64 data URLs. A model without image support returns 400 model_does_not_support_images.
PDF and other file inputs only work on models forwarded in Chat format as-is. To send a PDF to Claude, use a document block on the Messages endpoint.
metadata and provider are not forwarded upstream.

When a model has several vendors, add a provider object to the request body to pick or exclude vendors. Choosing vendors and their order →

Responselink

JSON

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1793952000,
  "model": "gpt-6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 10,
    "total_tokens": 31
  }
}

The x-wokey-request-id response header is the request's ID at Wokey. Include it when you report a problem.
Claude models: prompt_tokens excludes cache; cache reads and writes are listed separately in cache_read_input_tokens and cache_creation_input_tokens.
GPT models: prompt_tokens includes cached tokens; the cached count is in input_tokens_details.cached_tokens.
Other models: the upstream's own usage object, where cached tokens are usually in prompt_tokens_details.cached_tokens.
If a non-streaming request is still running after about 2 minutes, the gateway commits a 200 status and keeps the connection alive with whitespace. An error after that point arrives in the body of that 200 response. Use stream: true for long tasks.

Streaminglink

Each event is a data: line with one chunk JSON, and the stream ends with data: [DONE].

SSE

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{"content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{"content":" How can I help you today?"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":21,"completion_tokens":10,"total_tokens":31}}

data: [DONE]

The last chunk carries both finish_reason and usage. You don't need stream_options.include_usage; the gateway always returns usage.
Tool calls are not streamed piece by piece: the complete tool_calls arrive at the end of the stream.
Claude models, and reasoning models forwarded in Chat format as-is, stream their thinking in delta.reasoning_content. GPT models return no thinking text.
While waiting for the first upstream byte, the gateway sends periodic : keepalive comment lines, which SSE clients ignore.
If an error happens after the stream has started, the gateway sends a data: {"error": …} event followed by data: [DONE].

Error formatlink

JSON

{
  "error": {
    "code": "model_not_found",
    "message": "Model ID \"gpt-6-sun\" was not recognized. The correct model ID is \"gpt-6-sol\"; use it and try again. See https://wokey.ai/models for the full list.",
    "type": "invalid_request_error"
  }
}

Errors use the OpenAI shape: error.code is the code to branch on, and error.type is usually invalid_request_error. For what each status means and what to do, see Error codes & troubleshooting →