跳到导航

Chat Completions

Creates a model response for a chat conversation. This endpoint accepts OpenAI-compatible chat payloads and adds JoyToken routing, policy, wallet, and usage metadata around the provider call.

When JoyToken routes a request through orchestration (multi-task planning) mode, the gateway first produces a task plan, executes each task with a selected sub-model, and then aggregates a final answer. In this mode: the non-streaming choices[].message.content is a JSON-encoded array of per-task outputs (each with content and title), the top-level plan lists the tasks, and metadata is an array with one entry per task (including the reserved __planner__ and __final__ tasks). When streaming, a leading planning event arrives first (a chunk whose orchestration.phase is planning, carrying the ordered plan) followed by the __planner__ metadata event; then each task’s full content arrives as a chunk that carries an orchestration field (task_id, task_seq, task_status, title), each followed by one standalone metadata event (a single object, not an array) before [DONE].

身份验证

AuthorizationBearer

Use Authorization: Bearer $JOY_TOKEN_API_KEY.

请求头

X-Request-IDstring可选
Optional request identifier for log, billing, and debugging correlation.

请求

This endpoint expects an object.
modelstring必需

Use auto to let the gateway pick the model, or pass a concrete modelName from the model catalog to pin that model. Both ways are available to every account. When a model is pinned, tier is ignored, orchestration is not used, and there is no fallback to another model.

messageslist of objects必需

OpenAI-compatible chat messages.

tierenum可选
JoyToken model tier.
允许的值:
streamboolean可选默认为 false

Return an OpenAI-compatible SSE stream when true.

temperaturedouble可选0-2
Sampling temperature forwarded to the selected provider when supported.
top_pdouble可选0-1
Nucleus sampling value forwarded to the selected provider when supported.
max_tokensinteger可选>=1
Maximum output tokens. Also participates in JoyToken billing estimation.
userstring可选

Optional end-user identifier used as route session context.

toolslist of objects可选

OpenAI-compatible tool definitions.

响应头

X-DAOE-Failoverstring可选
Present on streaming responses when provider failover occurred.

响应

Successful chat completion response.
idstring
objectstring
choiceslist of objects
createdlong可选
modelstring可选
usageobject可选
metadatalist of objects可选

Array of JoyToken metadata objects. Always an array: a normal single-model response returns one element, while orchestration (multi-task planning) mode returns one element per task.

planlist of objects可选

Present only in orchestration mode. The ordered task plan produced by the planner. Each item maps to a task whose output appears as one entry in the JSON-encoded choices[].message.content array.

错误

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error