2026-10-20
（待译）
Model runs inference and lists model capabilities and prices through /model/v1. Each protocol surface follows its native provider (OpenAI / Anthropic / Google), so experience with that protocol applies. Differences: use catalog model ids unchanged, including creator prefixes, and only their declared supported_apis without protocol conversion; usage.cost, when present, is the customer charge in USD, not upstream cost; thinking levels map to the selected same-protocol model's effort or token budget, and unsupported disabling is rejected; explicitly unsupported fields return their documented error, ignored fields have no effect, and unknown top-level Chat, Responses, Messages and Embeddings fields pass to the same-protocol upstream. Allow room for reasoning within the completion-token cap before expecting tool arguments or structured output. Verify settled cost with praxis.model.generation.retrieve using X-Praxis-Generation-Id or chat providerMetadata.praxis.generationId; absent cost or id does not mean a free call. Start with praxis.model.models.list to choose a model by supported_apis, capabilities and per-unit prices.
加载中…| SDK | base URL | 认证头 | 能用的端点 |
|---|---|---|---|
| OpenAI SDK | Authorization: Bearer | 对话、生成响应、文本向量、生成图像、模型列表、会话（Conversations） | |
| Anthropic SDK | （SDK 自己补 /v1） | x-api-key 或 Authorization: Bearer | 发送消息、统计 token |
两家用同一把 Key、同一套模型名、同一个账单，换 SDK 不换别的。会话（创建、条目、删除）是跨调用的状态容器，形状与 OpenAI 官方 conversations 一致。
对话的请求体可以带 providerOptions.praxis：
| 字段 | 作用 |
|---|---|
models | 候选模型列表：请求的模型失败时按顺序换下一个 |
byok | 自带上游 Key（按供应商名给出）；这把 Key 不可用时自动改用平台的 |
order / only | 指定供应商的顺序或范围，只在带 byok 时可用 |
响应里的 providerMetadata.praxis 给出这次调用的 generationId、cost、credential（platform 或 byok）和实际服务的 model；拿 generationId 可以查询生成记录。其它端点目前不接受 providerOptions.praxis，带上会返回 400。
{type:"file", file_id:"<上传所得 ID>"}，直接读取当前租户的 File。file_id 读取上限为 24 MiB（25,165,824 字节，共享 96 MiB 内存预算按四倍预留）；超过此上限返回 413，并提示改用 HTTPS document_url（PDF 上限 50 MiB）。PNG/JPEG 仍限 10 MiB，按文件头识别类型；不存在或其他租户的文件统一返回 404。pages 是从 0 开始的页码数组；图片如指定 pages，只能为 [0]。文件读取失败不计费，请求日志仅记录 file_id，不保存文件原文。可选功能依模型而定，不支持的选项返回 400。错误为 problem+json；providerOptions.praxis 不适用于此端点。请求与响应字段的权威定义，见每个端点页链接的 OpenAI、Anthropic 或 Mistral 官方文档。OCR 通过 HTTP 调用，不在 OpenAI 或 Anthropic SDK 的端点中。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见错误；额度与响应头参见限流。
/model/v1/chat/completions● 支持X-OpenRouter-Metadatastring可选○ 当前不生效header: OpenRouter-style request header that asks for routing metadata in the response. It is accepted for compatibility and has no effect: the routing metadata is not returned.
接受但当前不生效；不会返回请求的路由元数据。
modelstring必填Model to use for completion
主模型；提供非空 models 时可省略，使用列表首项。
messagesarray必填◐ 部分支持List of messages for the conversation
文本、角色、历史和工具往返生效；图片受模型尺寸限制；file_id 可引用 user_data 图片、文本和 PDF；模型读取能力与失败处理见[文件引用指南](/docs/cloud/services/model/guides/files)。
元素按 role 区分（assistant / developer / system / tool / user），此处展开其中一种的形状
configuration_updateobject可选OpenRouter extension. Same as the system message `configuration_update`: changes reasoning effort from this point in the conversation onward without invalidating the prompt cache for the preceding turns.
contentstring | array可选Tool response content
namestring可选Optional name for the assistant
rolestring可选Role of the message author; always tool.
audioobject可选Audio output data or reference
imagesarray可选Generated images from image generation models
modelstring必填Model that generated this assistant message
reasoningstring可选Reasoning output
reasoning_detailsarray可选Reasoning details for extended thinking models
refusalstring可选Refusal message if content was refused
tool_callsarray可选Tool calls made by the assistant
tool_call_idstring可选ID of the assistant message tool call this message responds to
max_tokensinteger可选◐ 部分支持Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16.
deepseek-v4-flash、glm-5.3-flash 生效；qwen3.8-flash 的小预算可能不生效。与 max_completion_tokens 同传时本字段优先。
streamboolean可选◐ 部分支持Enable streaming response
流式正文和工具增量生效；gemini-2.5-flash 可能缺少结束标记，预算耗尽时 finish_reason 可能不准确。
temperaturenumber可选◐ 部分支持Sampling temperature (0-2)
在 /openai 的 deepseek-v4-flash 观察到效果；其余模型的采样差异无法确认。
top_pnumber可选◐ 部分支持Nucleus sampling parameter (0-1)
仅 /model 的 glm-5.3-flash 观察到效果；其余已测模型或协议面接受但未见效果。
toolsarray可选Available tools for function calling
已验证生效。
tool_choicestring | object可选◐ 部分支持Tool choice configuration
auto 生效；deepseek-v4-flash 忽略 none/required/具名函数；qwen3.8-flash 的 required/具名函数在思考模式报错；glm-5.3-flash 的具名函数结果不稳定。
functionobject必填The function the model must call.
typestring必填OpenRouter server-tool type to force (e.g. `openrouter:web_search`, `web_search`, `web_search_preview`).
response_formatobject可选◐ 部分支持Response format configuration
json_object 生效；json_schema 在 deepseek-v4-flash、qwen3.8-flash 生效，glm-5.3-flash 接受但未遵守。
按 type 区分（grammar / json_object / json_schema / python / text），此处展开其中一种的形状
typestring必填Always `python`. Discriminator that marks this object as a ChatFormatPythonConfig in a `type`-tagged union.
json_schemaobject必填JSON Schema configuration object
grammarstring必填Custom grammar for text generation
promptstring可选○ 当前不生效接受并忽略；Chat 仍须提供 messages，本字段不替代消息。
cache_controlobject可选Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format.
ttlstring可选Lifetime of an Anthropic-style cache breakpoint.
typestring必填Always `ephemeral`. Discriminator that marks this object as a AnthropicCacheControlDirective in a `type`-tagged union.
debugobject可选Debug options for inspecting request transformations (streaming only)
echo_upstream_bodyboolean可选○ 当前不生效If true, includes the transformed upstream request body in a debug chunk at the start of the stream. Only works with streaming mode.
接受但当前不生效。流式请求不会回显上游请求体。
frequency_penaltynumber可选◐ 部分支持Frequency penalty (-2.0 to 2.0)
deepseek-v4-flash、glm-5.3-flash 部分请求生效；qwen3.8-flash 在部分取值或协议面返回 400。
image_configobject可选Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.
logit_biasobject可选Token logit bias adjustments
logprobsboolean可选◐ 部分支持Return log probabilities
qwen3.8-flash 生效；deepseek-v4-flash 仅 /openai 生效，glm-5.3-flash 的两面结果不一致；gemini-2.5-flash 返回 400。
max_completion_tokensinteger可选◐ 部分支持Maximum tokens in completion
deepseek-v4-flash、glm-5.3-flash 生效；qwen3.8-flash 的小预算可能不生效或报超限。
metadataobject可选Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values)
min_pnumber可选○ 当前不生效Minimum probability threshold relative to the most likely token. Tokens with probability below min_p * (probability of top token) are filtered out. Not all providers support this parameter.
接受但当前不生效。
modalitiesarray可选Output modalities for the response. Supported values are "text", "image", and "audio".
modelsarray可选Models to use for completion
按顺序回退：主模型不存在、无同协议线路或上游失败均尝试下一项。可只给 models；响应 model 和费用归属最终完成请求的模型。
parallel_tool_callsboolean可选◐ 部分支持Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response.
false 在 qwen3.8-flash 生效；deepseek-v4-flash 接受但不生效；glm-5.3-flash 的两面结果不一致。
pluginsarray可选◐ 部分支持Plugins you want to enable for this request, including their settings.
支持 file-parser（pdf.engine 为 native、mistral-ocr→ocr、ocr、auto）和平台 guardrails。请求覆盖账户默认，锁定设置保留。web 等未实现插件、未知引擎或非法形状返回 400 并点名字段。
元素按 id 区分（auto-beta-router / auto-router / context-compression / file-parser / fusion / moderation / pareto-router / response-healing / web / web-fetch），此处展开其中一种的形状
allowed_modelsarray可选List of model patterns to filter which models the auto-beta-router can route between. Supports wildcards (e.g., "anthropic/*" matches all Anthropic models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. When not specified, every model ranked for the classified task type is a candidate, falling back to a default model set when rankings are unavailable.
cost_quality_tradeoffinteger可选Deprecated: Use cost_tier instead. Balances routing between cost and quality on a 0-10 scale. The auto-beta-router ranks models for the classified task type by community spend share, then filters candidates by their average cost per generation for that task. Higher values favor cheaper models: 10 keeps only models around the cheapest 10th percentile, while 0 permits models up to the 90th percentile for cost. Defaults to 9 when no cost setting is provided. It remains supported and retains ceiling behavior, but cost_tier takes precedence when both are provided.
cost_tierstring可选Named cost/quality setting. For auto-beta-router, tiers select cost-percentile bands: low = [0, 20), medium = [20, 40), high = [40, 60), xhigh = [60, 80), and max = [80, 100]. Takes precedence over the deprecated numeric cost_quality_tradeoff when both are provided.
enabledboolean可选Set to false to disable Fusion configuration for a run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool. Defaults to true.
excluded_modelsarray可选List of model patterns to exclude from auto-beta-router selection. Supports wildcards (e.g., "meta-llama/*" excludes all Llama models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Applied after allowed_models, so an excluded pattern always wins over an allowed one.
idstring可选Plugin id; always fusion.
pin_modelboolean可选When true, reuses the model from the most recent assistant message's `model` attribute for subsequent turns. Defaults to false.
enginestring可选The compression engine to use. Defaults to "middle-out".
exclude_domainsarray可选A list of domains to exclude from web search results. Supports wildcards (e.g. "*.substack.com") and path filtering (e.g. "openai.com/blog").
include_domainsarray可选A list of domains to restrict web search results to. Supports wildcards (e.g. "*.substack.com") and path filtering (e.g. "openai.com/blog").
max_resultsinteger可选Maximum number of search results to use.
max_usesinteger可选Maximum number of web fetches per request. Once exceeded, the tool returns an error.
modestring可选Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.
search_promptstring可选Prompt that introduces the search results to the model.
user_locationobject可选Approximate user location for location-biased search results.
allowed_domainsarray可选Only fetch from these domains.
blocked_domainsarray可选Never fetch from these domains.
max_content_tokensinteger可选Maximum content length in approximate tokens. Content exceeding this limit is truncated.
pdfobject可选Options for PDF parsing.
max_pricenumber可选Maximum input price in USD per million tokens. When set, quality-tier selection (min_coding_score) is bypassed: the router computes the Pareto frontier over the top coding models and routes to the best-scoring frontier model priced at or below this cap, falling back through cheaper frontier models, then non-frontier models. Enforced against the price source given by price_source. Returns 404 when no candidate satisfies the cap.
min_coding_scorenumber可选Minimum coding quality score between 0 and 1. Maps to internal quality tiers: >= 0.66 → high (top coding models), >= 0.33 → medium (strong modern flagships), < 0.33 → low (capable coders above the median). Omit to default to the highest tier (equivalent to >= 0.66). Not used when max_price is set (price-based selection takes over).
price_sourcestring可选Price source for the Pareto frontier cost axis and for enforcing max_price. "prompt" uses catalog list price (endpoint.pricing.prompt). "weighted_avg" uses traffic-weighted effective input price from ClickHouse, falling back to prompt price for models without traffic data. Defaults to "prompt".
analysis_modelsarray可选For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, slugs of models to run in parallel as the "expert panel" the analyst analyzes. Each model receives the same user prompt with web_search + web_fetch enabled. Capped at 8 models to bound cost amplification. When omitted, defaults to the Quality preset from the /labs/fusion UI (~anthropic/claude-opus-latest, ~openai/gpt-sol-latest, ~google/gemini-pro-latest).
max_tool_callsinteger可选For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, the maximum number of tool-calling steps each panelist (analysis model) and the analyst model may take during their agentic web-research loop. Models with web_search/web_fetch enabled iterate until they produce a text response or hit this ceiling. Defaults to 4. Capped at 16.
modelstring必填For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, the slug of the model that performs both the analyst step (with web_search + web_fetch) and the final synthesis. When omitted, defaults to the first model in the Quality preset.
presetstring可选Configuration for a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool. A curated OpenRouter preset (slugs follow `<task>-<tier>`, e.g. `general-high`). Expands server-side into the preset's analysis_models panel and analyst model, so callers never name individual models. Explicitly provided `analysis_models` / `model` take precedence.
toolsarray可选For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, server tools available to panelist and analyst inner calls. Each entry uses the same `{ type, parameters? }` shorthand as the outer Chat Completions request. When omitted, defaults to `[{ type: "openrouter:web_search" }, { type: "openrouter:web_fetch" }]`. Pass an empty array to disable tools entirely (panelists answer from parametric knowledge only).
predictionobject可选Static predicted output content. Supported models can use this to reduce latency when much of the response is known in advance.
contentstring | array必填Predicted output: a string or an array of text parts.
typestring必填Always `content`. Discriminator that marks this object as a Prediction in a `type`-tagged union.
presence_penaltynumber可选◐ 部分支持Presence penalty (-2.0 to 2.0)
deepseek-v4-flash 的 /openai 面观察到效果；qwen3.8-flash 部分请求返回 400，其余不可观测。
prompt_cache_keystring可选Caller-chosen key that groups requests with a long shared prefix so that they can reuse the provider's prompt cache; null for none.
prompt_cache_optionsobject可选Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer.
modestring必填Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint.
ttlstring可选Lifetime of cache entries, for example 30m; null leaves the provider default.
providerobject可选◐ 部分支持When multiple model providers are available, optionally indicate your routing preference.
只有选择具体供应商（order / only / ignore）仅限 BYOK、返回 400；require_parameters 生效，其余选项接受但不生效。
allow_fallbacksboolean可选○ 当前不生效Whether to allow backup providers to serve requests - true: (default) when the primary provider (or your custom providers in "order") is unavailable, use the next best provider. - false: use only the primary/custom provider, and return the upstream error if it's unavailable.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
data_collectionstring可选○ 当前不生效Data collection setting. If no available model provider meets the requirement, your request will return an error. - allow: (default) allow providers which store user data non-transiently and may train on it - deny: use only providers which do not collect user data.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
enforce_distillable_textboolean可选Whether to restrict routing to only models that allow text distillation. When true, only models where the author has allowed distillation will be used.
ignorearray可选○ 未支持List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request.
选择具体供应商（order / only / ignore）仅限 BYOK，平台凭证下返回 400 PROVIDER_SELECTION_NOT_ALLOWED。
max_priceobject可选○ 当前不生效The object specifying the maximum price you want to pay for this request. USD price per million tokens, for prompt and completion.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
onlyarray可选○ 未支持List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request.
选择具体供应商（order / only / ignore）仅限 BYOK，平台凭证下返回 400 PROVIDER_SELECTION_NOT_ALLOWED。
orderarray可选○ 未支持An ordered list of provider slugs. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message.
选择具体供应商（order / only / ignore）仅限 BYOK，平台凭证下返回 400 PROVIDER_SELECTION_NOT_ALLOWED。
preferred_max_latencynumber | object可选Preferred maximum latency (in seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints above the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold.
preferred_min_throughputnumber | object可选Preferred minimum throughput (in tokens per second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints below the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold.
quantizationsarray可选○ 当前不生效A list of quantization levels to filter the provider by.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
require_parametersboolean可选Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest.
只走能表达全部参数的线路；平台凭证下可用。
sortstring | object可选○ 当前不生效The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
zdrboolean可选○ 当前不生效Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used.
接受但当前不生效（不属于供应商选择，平台凭证下可用）。
reasoningobject可选Configuration options for reasoning models
effortstring可选◐ 部分支持Constrains effort on reasoning for reasoning models
none 仅在 qwen3.8-flash 可靠关闭思考；deepseek-v4-flash 和 glm-5.3-flash 未遵守。
summarystring可选○ 当前不生效How detailed the reasoning summary should be.
接受但当前不生效。deepseek-v4-flash 未返回请求的摘要。
reasoning_effortstring可选◐ 部分支持Shorthand for setting reasoning effort. Equivalent to setting reasoning.effort. Cannot be used simultaneously with reasoning.effort if they differ.
none 在 qwen3.8-flash 关闭思考；deepseek-v4-flash 仍思考，glm-5.3-flash 的档位效果不符合预期。
repetition_penaltynumber可选Penalizes tokens based on how much they have already appeared in the text. A value of 1.0 means no penalty. Values above 1.0 penalize repeated tokens more strongly. Not all providers support this parameter.
routestring可选**DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none").
seedinteger可选○ 当前不生效Random seed for deterministic outputs
接受但当前不生效。deepseek-v4-flash、glm-5.3-flash、qwen3.8-flash 同 seed 不能复现输出。
service_tierstring可选The service tier to use for processing this request. `fast` is accepted as an alias for `priority`.
session_idstring可选A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.
stopstring | array可选◐ 部分支持Stop sequences (up to 4)
qwen3.8-flash 生效；deepseek-v4-flash、glm-5.3-flash 可能截断思考并返回空正文。
stop_server_tools_whenarray可选Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call.
元素按 type 区分（finish_reason_is / has_tool_call / max_cost / max_tokens_used / step_count_is），此处展开其中一种的形状
step_countinteger可选Number of steps after which the loop stops.
typestring可选Always `finish_reason_is`. Discriminator that marks this object as a StopServerToolsWhenFinishReasonIs in a `type`-tagged union.
tool_namestring可选Name of the tool whose call stops the loop.
max_tokensinteger可选Cumulative token count after which the loop stops.
max_cost_in_dollarsnumber可选Cumulative cost in USD after which the loop stops.
reasonstring可选Finish reason that stops the loop.
stream_optionsobject可选Streaming configuration options
include_usageboolean可选○ 当前不生效Deprecated: This field has no effect. Full usage details are always included.
接受但当前不生效。无论 true、false 或省略，流末尾都会返回 usage。
top_anumber可选○ 当前不生效Consider only tokens with "sufficiently high" probabilities based on the probability of the most likely token. Not all providers support this parameter.
接受但当前不生效。
top_kinteger可选◐ 部分支持Limits the model to choose from the top K most likely tokens at each step. A value of 1 means the model will always pick the most likely next token. Not all providers support this parameter.
已测模型接受但未见采样效果；/model 的 deepseek-v4-flash 返回错误。
top_logprobsinteger可选◐ 部分支持Number of top log probabilities to return (0-20)
需与 logprobs=true 同传；支持度随 logprobs 和所选模型而异。
traceobject可选Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.
generation_namestring可选Name of this generation in the trace.
parent_span_idstring可选Id of the parent span in the trace.
span_namestring可选Name of this request's span in the trace.
trace_idstring可选Id that groups several requests into one trace.
trace_namestring可选Name of the trace.
userstring可选Per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.
storeboolean可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
max_output_tokensinteger可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
thinkingobject可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
web_search_optionsobject可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
functionsarray可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
audioobject可选○ 当前不生效接受但当前不生效。此结论仅适用于 Chat Completions。
ninteger可选◐ 部分支持glm-5.3-flash 生效；deepseek-v4-flash 接受但当前不生效；qwen3.8-flash 返回错误。
usageobject可选○ 当前不生效接受并忽略；用量默认始终返回，include 不改变行为。
transformsarray可选○ 当前不生效接受并忽略；不执行 middle-out 或其他消息变换，保留原消息。
deferred_toolsobject可选○ 当前不生效接受并忽略；尚未实现 OpenRouter 延迟工具协议。
structured_outputsboolean可选○ 当前不生效接受并忽略此开关；结构化输出使用 response_format，支持度见该字段。
include_reasoningboolean可选○ 当前不生效接受并忽略此旧别名；思考配置使用 reasoning，支持度见该字段。
safe_promptboolean可选○ 当前不生效接受并忽略；未实现 Mistral 的 safe_prompt 开关。
raw_modeboolean可选○ 当前不生效接受并忽略；未实现 Hyperbolic 的 raw_mode 开关。
providerOptionsobject可选◐ 部分支持providerOptions.praxis.models 与顶层 models 使用同一有序回退。order/only 仅允许与已有的请求级 BYOK 凭证同时使用；非 BYOK 返回 400。
praxisobject必填Platform options: ordered model fallback, request-level BYOK credentials and credential-gated provider selection.
200 chat.completion
stream=true 时以 SSE 增量返回（text/event-stream）。
未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Chat completion (application/json) or streamed chunks (text/event-stream)
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the completion. |
| object | string | Object type; always `chat.completion`. |
| created | number | Unix time in seconds at which the completion was created. |
| model | string | Model that produced the completion; with fallback this is the model that finally answered. |
| choices | array<object> | Completion choices; one entry per generated answer. |
| choices[].index | number | Zero-based index of the choice. |
| choices[].message | object | The message the model generated. |
| choices[].finish_reason | string | null | Why generation stopped, for example `stop`, `length` or `tool_calls`; null while a stream is still generating. |
| choices[].logprobs | any | null | Log probabilities of the output tokens, when requested; null otherwise. |
| usage | object | Token usage of the request. |
| usage.prompt_tokens | number | Number of tokens in the prompt. |
| usage.completion_tokens | number | Number of tokens in the completion. |
| usage.total_tokens | number | Prompt plus completion tokens. |
| usage.prompt_tokens_details | object | Breakdown of the prompt tokens. |
| usage.completion_tokens_details | object | Breakdown of the completion tokens. |
| usage.prompt_cache_hit_tokens | number | Prompt tokens served from the cache, as reported by providers that use this DeepSeek-style counter. |
| usage.prompt_cache_miss_tokens | number | Prompt tokens not served from the cache, as reported by providers that use this DeepSeek-style counter. |
| system_fingerprint | string | null | Backend fingerprint; always null on this face. |
| service_tier | string | null | Service tier the provider used; null when not reported. |
| providerMetadata | object | Platform metadata of the call. |
| providerMetadata.praxis | object | Platform metadata of the call: generation id, cost, credential kind and serving model. |
text/event-stream — chunk / 事件对象
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Optional id of the server-sent event. |
| event | string | Name of the server-sent event. |
| data | object | string | Payload of the server-sent event. |
| data.id | string | Id of the completion; every chunk of one stream carries the same id. |
| data.object | string | Object type; always `chat.completion.chunk`. |
| data.created | number | Unix time in seconds at which the completion was created. |
| data.model | string | Model that produced the completion; with fallback this is the model that finally answered. |
| data.choices | array<object> | Completion choices of the chunk. |
| data.providerMetadata | object | Platform metadata of the call. |
/model/v1/responses● 支持modelstring可选◐ 部分支持Model id, for example one listed by listModels?type=language. Router support (partial): Verified on glm-5.3-flash and deepseek-flash; models without Responses support return 404.
已验证支持 glm-5.3-flash、deepseek-flash；没有 Responses 协议的模型返回 404。
inputstring | array可选◐ 部分支持Input for a response request - can be a string or array of items
字符串、消息数组、input_text、input_image 和函数往返生效；input_file 在 glm-5.3-flash 报错、deepseek-flash 忽略；托管文件引用返回 400。
streamboolean可选◐ 部分支持Whether to stream the response as server-sent events. Router support (partial): Works on deepseek-flash; glm-5.3-flash returns 400.
deepseek-flash 生效；glm-5.3-flash 返回 400。
temperaturenumber可选◐ 部分支持Sampling temperature between 0 and 2; higher values make output more random. Router support (partial): Partly effective on glm-5.3-flash; 2 may produce empty or garbled text. Effects on deepseek-flash are unobservable.
glm-5.3-flash 部分生效，2 可能返回空文本或乱码；deepseek-flash 的效果不可观测。
top_pnumber可选◐ 部分支持Nucleus sampling: only tokens within this cumulative probability are considered. Router support (partial): Sampling changes were observed on glm-5.3-flash; effects on deepseek-flash are unobservable.
glm-5.3-flash 观察到采样变化；deepseek-flash 不可观测。
toolsarray可选◐ 部分支持Tools the model may call: functions, built-in tools and MCP servers. Router support (partial): function works. web_search, code_interpreter, image_generation, mcp and computer_use are accepted but currently have no effect; file_search returns 404.
function 生效；web_search、code_interpreter、image_generation、mcp、computer_use 接受但当前不生效；file_search 返回 404。
tool_choicestring | object可选◐ 部分支持How the model picks tools: a mode string or a specific tool.
auto 生效；deepseek-flash 的 required/具名函数需 reasoning.effort=none；allowed_tools 在 glm-5.3-flash 被忽略，在 deepseek-flash 返回 422。
namestring必填Name of the function or tool the model must call.
typestring必填Kind of tool the model must call.
modestring必填auto lets the model pick among the allowed tools or none; required forces a call to one of them.
toolsarray必填The allowed tools, each as a tool reference such as {type: function, name}.
promptobject可选○ 未支持Reference to a saved prompt template and its variables. We don't have a Prompts resource yet — any id you pass returns 404 object_not_found.
当前没有可引用的提示词模板；传入模板 id 返回 404。
idstring必填Id of the stored prompt template.
variablesobject可选Values for the template variables, keyed by variable name; a value is a string or an input text, image or file part.
backgroundboolean可选◐ 部分支持Whether to run the model response in the background. Available only when the routed model has Router-built background support — Router returns status "queued" immediately, then stream-calls the upstream itself, runs the job to a terminal state, and bills usage exactly once, while the client polls GET /v1/responses/{id} (this does not mean the upstream natively supports OpenAI's background parameter). A provider without this capability still returns HTTP 400 (native_responses_background_unsupported) for background:true. Cancel (POST /v1/responses/{id}/cancel) can only stop our own read of the upstream stream — it cannot guarantee upstream compute already issued stops — and billing reflects only usage actually received, falling back to the platform's general "upstream reported no usage" rule when none was received.
deepseek-flash 生效；glm-5.3-flash 返回 400。background 与 stream 同传时返回 JSON。
includearray可选◐ 部分支持Forwarded to the upstream model as-is; only takes effect for capabilities the model has (e.g., reasoning content, web search results). Fields the model doesn't support are ignored.
deepseek-flash 返回 logprobs；reasoning.encrypted_content 仅为占位串。glm-5.3-flash 接受但当前不生效。
instructionsstring可选System or developer instructions inserted at the start of the context. Router support (supported): Verified to take effect.
已验证生效。
max_output_tokensinteger可选Upper bound on generated tokens, including reasoning tokens. Router support (supported): A positive value controls the output budget; zero returns 400.
正数控制输出预算；0 返回 400。
metadataobject可选◐ 部分支持Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.
glm-5.3-flash 回显；deepseek-flash 接受但当前不生效，响应及读取均为空对象。
parallel_tool_callsboolean可选◐ 部分支持Whether the model may call several tools in one turn. Router support (partial): true permits multiple calls; false is accepted but currently has no effect and may still return multiple calls.
true 可返回多个调用；false 接受但当前不生效，仍可能返回多个调用。
previous_response_idany可选ID of a previous response. Its owner may continue it; the model field can then be omitted. The platform expands the stored history before calling the upstream.
平台将祖先的输入与输出和本轮 input 合并，发往上游前移除 previous_response_id；没有活副本或不属于当前租户时返回 404 previous_response_not_found。
prompt_cache_keystring可选Caller-chosen key that groups requests with a long shared prefix so that they can reuse the provider's prompt cache.
prompt_cache_optionsobject可选Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer.
modestring必填Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint.
ttlstring可选Lifetime of cache entries, for example 30m; null leaves the provider default.
reasoningobject可选Configuration for reasoning mode in the response
contextstring可选Controls which reasoning is available to the model. `auto` uses the model default (same as omitting); `all_turns` includes reasoning from earlier turns passed in input; `current_turn` limits to the current turn only. Only supported by OpenAI GPT-5.6 and newer.
effortstring可选◐ 部分支持How much reasoning the model should spend.
deepseek-flash 的 none 可关闭思考，其余档位不保证单调；glm-5.3-flash 接受但当前不生效，none 仍思考。
modestring可选Selects the reasoning mode. `standard` is the default; `pro` engages deeper reasoning on models that support it, billed at standard token rates. Only supported by OpenAI GPT-5.6 and newer.
summarystring可选◐ 部分支持How detailed the reasoning summary should be.
glm-5.3-flash 的 concise 偶发有摘要，auto/detailed 未见；deepseek-flash 接受但当前不生效。
enabledboolean可选Whether reasoning is on for models that let you switch it.
max_tokensinteger可选Upper bound on reasoning tokens, for models that take a reasoning budget.
safety_identifierstring可选Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, we fold it into the hashed identity sent upstream and never forward it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.
service_tierstring可选Requested service tier; its effect is currently unobservable.
storeboolean可选Whether to store the response server-side so it can be retrieved or continued later via previous_response_id. Defaults to true; pass false to opt out.
true 保存响应供读取；false 不保存，读取返回 404。
textobject可选Text output configuration including format and verbosity
formatobject可选◐ 部分支持Text response format configuration
json_object、json_schema 生效（预算需足够）；text 在 glm-5.3-flash 偶发 400，在 deepseek-flash 生效。
verbositystring可选○ 当前不生效How long the answer should be. Router support (ignored): Accepted but currently has no effect. No verbosity effect was observed on glm-5.3-flash or deepseek-flash.
接受但当前不生效。glm-5.3-flash、deepseek-flash 均未观察到长度变化。
top_logprobsinteger可选◐ 部分支持Number of most likely tokens whose log probabilities are returned per position, from 0 to 20. Router support (partial): Works on deepseek-flash with values 0–20; glm-5.3-flash returns empty logprobs.
deepseek-flash 生效，允许 0–20；glm-5.3-flash 返回空 logprobs。
truncationstring可选How to handle input that exceeds the context window.
userstring可选A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters.
conversationstring可选The conversation this response belongs to (a conversation id string, or a `{id}` object). Before the request reaches the upstream provider, we prepend that conversation's existing items to this request's input; after the response completes, this turn's input and output items are appended back to the conversation. Only the conversation's owner may reference it — otherwise 404 object_not_found; cannot be used together with previous_response_id — sending both returns 400.
会话历史进入本次输入，响应条目追加到会话；不能与 previous_response_id 同传。
context_managementarray可选Context management configuration for this request (e.g. automatic compaction once a token threshold is exceeded).
moderationobject可选Configuration for running moderation on the input and output of this response.
prompt_cache_retentionstring可选The retention policy for the prompt cache. Set to 24h to keep cached prefixes active for up to 24 hours.
stream_optionsobject可选Options for streaming responses. Only set this when stream=true (e.g. whether to include usage statistics at the end of the stream).
access_programsobject可选○ 未支持已识别的官方字段；平台未实现访问计划，传入返回 400 并明确说明不支持。
200 response
stream=true 时以 SSE 增量返回（text/event-stream）。
未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Successful response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| background | boolean | null | Whether the response was started in background mode. |
| completed_at | integer | null | Unix time in seconds at which the response finished; null while it has not finished. |
| created_at | integer | Unix time in seconds at which the response was created. |
| error | object | null | Error information returned from the API |
| error.code | string | Machine-readable error code. |
| error.message | string | Human-readable error message. |
| frequency_penalty | number | null | The frequency penalty that applied to the request, if any. |
| id | string | Unique id of the response; use it as response_id to retrieve, cancel or delete it, or as previous_response_id to continue the conversation. |
| incomplete_details | object | null | Why the response stopped before finishing; null for complete responses. |
| incomplete_details.reason | string | Why the response is incomplete. |
| instructions | string | array<object> | null | Input of the request: a string or an array of input items. |
| max_output_tokens | integer | null | Upper bound on generated tokens that applied to the request; null when none was set. |
| max_tool_calls | integer | null | Upper bound on built-in tool calls that applied to the request; null when none was set. |
| metadata | object | null | Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed. |
| model | string | Model that produced the response. |
| object | string | Object type; always `response`. |
| output | array<object> | Items the model produced, in order: messages, reasoning, tool calls and tool results. |
| output[].content | array<object> | array | null | string | Content parts of the message: output text or refusal. / Reasoning text parts, when the provider returns them. / Text content of the fetched page. |
| output[].id | string | Id of the message item. / Id of the reasoning item. / Id of the function call item. / Id of the web search call item. / Id of the file search call item. / Id of the image generation call item. / Id of the code interpreter call item. / Id of the computer call item. / Id of the datetime server tool item. / Id of the web search server tool item. / Id of the code interpreter server tool item. / Id of the file search server tool item. / Id of the image generation server tool item. / Id of the browser use server tool item. / Id of the bash server tool item. / Id of the text editor server tool item. / Id of the apply_patch server tool item. / Id of the apply_patch call item. / Id of the shell call item. / Id of the shell call output item. / Id of the shell server tool item. / Id of the web fetch server tool item. / Id of the tool search server tool item. / Id of the memory server tool item. / Id of the MCP server tool item. / Id of the model search server tool item. / Id of the fusion server tool item. / Id of the advisor server tool item. / Id of the subagent server tool item. / Id of the files server tool item. / Id of the custom tool call item. |
| output[].phase | string | null | The phase of an assistant message. Use `commentary` for an intermediate assistant message and `final_answer` for the final assistant message. For follow-up requests with models like `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages. |
| output[].role | string | Role of the author; always assistant. |
| output[].status | string | Status of the message item. / Status of the reasoning item. / Status of the function call item. / Status of a web search call. / Status of a web search call. / Status of an image generation call. / Status of the code interpreter call. / Status of the computer call item. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call that can fail. / Status of a tool call. / Status of a tool call. / Lifecycle state of an `apply_patch_call` output item. / Status of a shell call or its output. / Status of a shell call or its output. / Status of a tool call that can fail. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call that can fail. / Status of a tool call that can fail. / Status of a tool call. / Status of the custom tool call item. |
| output[].type | string | Always `message`. Discriminator that marks this object as a OutputMessage in a `type`-tagged union. / Always `reasoning`. Discriminator that marks this object as a OutputItemReasoning in a `type`-tagged union. / Always `function_call`. Discriminator that marks this object as a OutputItemFunctionCall in a `type`-tagged union. / Always `web_search_call`. Discriminator that marks this object as a OutputItemWebSearchCall in a `type`-tagged union. / Always `file_search_call`. Discriminator that marks this object as a OutputItemFileSearchCall in a `type`-tagged union. / Always `image_generation_call`. Discriminator that marks this object as a OutputItemImageGenerationCall in a `type`-tagged union. / Always `code_interpreter_call`. Discriminator that marks this object as a OutputItemCodeInterpreterCall in a `type`-tagged union. / Always `computer_call`. Discriminator that marks this object as a OutputComputerCallItem in a `type`-tagged union. / Always `openrouter:datetime`. Discriminator that marks this object as a OutputDatetimeItem in a `type`-tagged union. / Always `openrouter:web_search`. Discriminator that marks this object as a OutputWebSearchServerToolItem in a `type`-tagged union. / Always `openrouter:code_interpreter`. Discriminator that marks this object as a OutputCodeInterpreterServerToolItem in a `type`-tagged union. / Always `openrouter:file_search`. Discriminator that marks this object as a OutputFileSearchServerToolItem in a `type`-tagged union. / Always `openrouter:image_generation`. Discriminator that marks this object as a OutputImageGenerationServerToolItem in a `type`-tagged union. / Always `openrouter:browser_use`. Discriminator that marks this object as a OutputBrowserUseServerToolItem in a `type`-tagged union. / Always `openrouter:bash`. Discriminator that marks this object as a OutputBashServerToolItem in a `type`-tagged union. / Always `openrouter:text_editor`. Discriminator that marks this object as a OutputTextEditorServerToolItem in a `type`-tagged union. / Always `openrouter:apply_patch`. Discriminator that marks this object as a OutputApplyPatchServerToolItem in a `type`-tagged union. / Always `apply_patch_call`. Discriminator that marks this object as a OutputApplyPatchCallItem in a `type`-tagged union. / Always `shell_call`. Discriminator that marks this object as a OutputShellCallItem in a `type`-tagged union. / Always `shell_call_output`. Discriminator that marks this object as a OutputShellCallOutputItem in a `type`-tagged union. / Always `openrouter:shell`. Discriminator that marks this object as a OutputShellServerToolItem in a `type`-tagged union. / Always `openrouter:web_fetch`. Discriminator that marks this object as a OutputWebFetchServerToolItem in a `type`-tagged union. / Always `openrouter:tool_search`. Discriminator that marks this object as a OutputToolSearchServerToolItem in a `type`-tagged union. / Always `openrouter:memory`. Discriminator that marks this object as a OutputMemoryServerToolItem in a `type`-tagged union. / Always `openrouter:mcp`. Discriminator that marks this object as a OutputMcpServerToolItem in a `type`-tagged union. / Always `openrouter:experimental__search_models`. Discriminator that marks this object as a OutputSearchModelsServerToolItem in a `type`-tagged union. / Always `openrouter:fusion`. Discriminator that marks this object as a OutputFusionServerToolItem in a `type`-tagged union. / Always `openrouter:advisor`. Discriminator that marks this object as a OutputAdvisorServerToolItem in a `type`-tagged union. / Always `openrouter:subagent`. Discriminator that marks this object as a OutputSubagentServerToolItem in a `type`-tagged union. / Always `openrouter:files`. Discriminator that marks this object as a OutputFilesServerToolItem in a `type`-tagged union. / Always `custom_tool_call`. Discriminator that marks this object as a OutputCustomToolCallItem in a `type`-tagged union. |
| output[].encrypted_content | string | null | Opaque encrypted reasoning; send it back unchanged to let the model continue its reasoning on the next turn. |
| output[].summary | array<object> | Summary parts of the reasoning. |
| output[].format | string | null | Wire format of the reasoning details, which names the provider family that produced them. |
| output[].signature | string | null | A signature for the reasoning content, used for verification |
| output[].arguments | string | string | null | string | null | string | null | string | string | null | JSON-encoded arguments the model produced for the function. / The raw tool-call arguments string as emitted by the model. / The raw tool-call arguments string as emitted by the model. Echo back unchanged when replaying history; used verbatim to preserve provider prompt-cache prefixes. / The raw tool-call arguments string as emitted by the model. / The JSON arguments submitted to the search tool (e.g. {"query":"Claude"}) / The raw tool-call arguments string as emitted by the model. |
| output[].async | boolean | True when the model called a tool declared with `async: true` and may continue its turn before the output is returned. Return the result in a later request as a `function_call_output` with this `call_id`. |
| output[].call_id | string | string | null | string | string | string | string | string | null | string | string | null | string | Id of the call; the function_call_output item that answers it repeats it as call_id. / Id of the call; the computer_call_output item that answers it repeats it as call_id. / The model-generated tool call id from the originating turn. / Id of the apply_patch tool call. / Id of the call; the apply_patch_call_output item that answers it repeats it as call_id. / Id of the call; the shell_call_output item that answers it repeats it as call_id. / Id of the shell call this output answers. / The model-generated tool call id from the originating turn. / EXPERIMENTAL — subject to change without notice. The `call_id` of the tool call that spawned this subagent. This id will also be included as the `subagent_id` on any `function_call` items created by the subagent. This must be returned in the request so the `function_call` can be matched with the correct subagent. A suspended `in_progress` item is announced once and never re-emitted or terminally closed — completion arrives as a new item with the same `call_id`. / The model-generated tool call id from the originating turn. / Id of the call; the custom_tool_call_output item that answers it repeats it as call_id. |
| output[].name | string | Name of the function being called. / Configured name of the subagent that executed the task (the `name` on its tool entry). Present only for named subagents; omitted for an unnamed (default) subagent. / Name of the custom tool being called. |
| output[].namespace | string | Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) |
| output[].subagent_id | string | EXPERIMENTAL — subject to change without notice. String id that matches the `call_id` of the `openrouter:subagent` server tool call that spawned the subagent. Present on every `function_call` item the subagent projects; absent on ordinary function calls. |
| output[].subagent_items | array<object> | EXPERIMENTAL — subject to change without notice. The subagent's output items produced on this turn. Treat this as an opaque object; you must replay it in the request so that the subagent can continue execution of the tool with the same context. If a subagent created multiple parallel tool calls, only the first tool call will have this field. The other tool calls will only have `subagent_id`. Present only if the tool call originates from a subagent spawned by the `openrouter:subagent` server tool. |
| output[].action | object | any | object | string | object | object | string | The search action the model took: a search, opening a page, or finding a pattern in a page. / The action the model asks the client to perform on the computer. / The search action performed, matching OpenAI web_search_call.action shape. Includes the query the model issued and optional source URLs returned by the search provider. / The browser action that was performed. / The commands the model asks the client to run. / The commands that were run. / Memory action that was performed. |
| output[].queries | array<string> | Queries the model ran against the vector stores. / Queries that ran against the vector stores. |
| output[].result | string | null | string | Base64-encoded generated image; null while generation has not finished. / The generated image as a base64-encoded string or URL, matching OpenAI image_generation_call format / JSON-serialized result of the file operation. |
| output[].prompt | string | The prompt (possibly rewritten) that the image was generated from. / The prompt the executor sent to the advisor. |
| output[].code | string | null | string | The code the interpreter ran; null while it is still being written. / The code that ran. |
| output[].container_id | string | Id of the container the code ran in. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. |
| output[].outputs | array | null | Outputs of the run: logs and images; null while the run has not finished. |
| output[].pending_safety_checks | array<object> | Safety checks that must be acknowledged before the action is performed. |
| output[].datetime | string | ISO 8601 datetime string |
| output[].timezone | string | IANA timezone name |
| output[].exitCode | integer | Exit code of the run; 0 means success. / Exit code of the command; 0 means success. |
| output[].language | string | Language of the code that ran. |
| output[].stderr | string | Standard error output of the code. / Standard error output of the command. |
| output[].stdout | string | Standard output of the code. / Standard output of the command. |
| output[].imageB64 | string | Base64-encoded generated image. |
| output[].imageUrl | string | URL of the generated image. |
| output[].revisedPrompt | string | Prompt after the image model rewrote it. |
| output[].screenshotB64 | string | Base64-encoded screenshot taken after the action. |
| output[].command | string | The bash command that ran. / Editor command that ran. |
| output[].error | string | The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. A non-zero `exitCode` is a command failure, not a tool failure. / The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'incomplete'` and an empty `output`; absent on a successful call. / The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. `output` is omitted when `error` is set. / The error message if the fetch failed. / Error message when the fusion run did not produce an analysis result. / Error message when the advisor call did not produce advice. Set together with `status: 'failed'` on the terminal item. / Error message when the subagent task did not produce an outcome. Set together with `status: 'failed'` on the terminal item. / Error message when the file operation failed. |
| output[].files | array<object> | Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API. |
| output[].filePath | string | Path of the file the command worked on. |
| output[].operation | object | string | The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. / The file operation performed (list, read, write, or edit). |
| output[].max_output_length | integer | null | Maximum number of characters of output that was kept; null for no limit. |
| output[].output | array<object> | Output of each command, in the order the commands ran. |
| output[].httpStatus | integer | The HTTP status code returned by the upstream URL fetch. |
| output[].title | string | Title of the fetched page. |
| output[].url | string | URL that was fetched. |
| output[].query | string | The tool search query. / The model search query. |
| output[].key | string | Key of the memory entry. |
| output[].value | any | Value of the memory entry; absent for reads that found nothing and for deletes. |
| output[].serverLabel | string | Label of the MCP server. |
| output[].toolName | string | Name of the MCP tool that was called. |
| output[].analysis | object | Structured analysis produced by the fusion analyst model. |
| output[].failed_models | array<object> | Models that were requested as part of the analysis panel but did not produce a response. Present when at least one requested analysis model failed. The fusion result is still usable but was produced from a degraded panel. |
| output[].failure_reason | string | Typed failure reason when the fusion run failed. Possible values include: all_panels_failed, insufficient_credits, rate_limited, invalid_model, judge_not_valid_json, judge_schema_mismatch, judge_upstream_error, judge_empty_completion. The four analysis-stage codes keep their pre-rename `judge_` spelling so existing consumers keep matching. The consumer-cancellation code is `cancelled`. |
| output[].responses | array<object> | Analysis models that produced a response in this fusion run, with each model's full panel content. |
| output[].sources | array<object> | Web pages the analysis panels and analyst retrieved via web search during this fusion run, deduplicated by URL across the whole run. Present when at least one model cited a source. |
| output[].advice | string | The advisor model's response (the advice text returned to the executor). |
| output[].instance_name | string | Provider-safe function name of the specific advisor instance that produced this item (e.g. `openrouter_advisor__1`). Present only when more than one advisor tool is configured; omitted for the default single advisor. Echo this field back unchanged so the advisor's cross-request memory stays namespaced to the correct instance. This identity is positional: it is derived from the index of the advisor entry in the request `tools` array, so clients must keep the order of advisor tool entries stable across requests in a conversation. Reordering or inserting advisor entries shifts these names and causes each advisor's cross-request memory to be attributed to the wrong instance. / Provider-safe function name of the specific subagent instance that produced this item (e.g. `openrouter_subagent__1`). Present only on items from non-default instances — the second and later subagent entries in the request `tools` array. The first (default) instance omits it, even when multiple subagents are configured. When a replayed item echoes this field back, the transcript rehydrates the call under that instance's tool. This identity is positional: it is derived from the index of the subagent entry in the request `tools` array, so keep the order of subagent entries stable across requests in a conversation. |
| output[].model | string | Slug of the advisor model that was consulted. / Slug of the worker model that executed the task. |
| output[].outcome | string | The worker model's result (the outcome text returned to the delegating model). |
| output[].task_description | string | The task description the delegating model sent to the worker. |
| output[].task_name | string | The short task identifier the delegating model supplied. |
| output[].file_id | string | The target file id supplied in the tool-call arguments. |
| output[].filename | string | The target filename supplied in the tool-call arguments. |
| output[].input | string | Free-form input the model produced for the custom tool. |
| output_text | string | Convenience concatenation of all output text of the response. |
| parallel_tool_calls | boolean | Whether the model was allowed to call several tools in one turn. |
| presence_penalty | number | null | The presence penalty that applied to the request, if any. |
| previous_response_id | string | null | Id of the response this one continued; null when it started a new conversation. |
| prompt | object | null | Reference to a stored prompt template with its variables. |
| prompt.id | string | Id of the stored prompt template. |
| prompt.variables | object | null | Values for the template variables, keyed by variable name; a value is a string or an input text, image or file part. |
| prompt_cache_key | string | null | Cache key the request supplied to improve prompt cache hits; null when none was set. |
| prompt_cache_options | object | null | Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. |
| prompt_cache_options.mode | string | Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint. |
| prompt_cache_options.ttl | string | null | Lifetime of cache entries, for example 30m; null leaves the provider default. |
| reasoning | object | null | Reasoning settings that applied: effort, summary verbosity, mode and context. |
| reasoning.context | string | null | Controls which reasoning is available to the model. `auto` uses the model default (same as omitting); `all_turns` includes reasoning from earlier turns passed in input; `current_turn` limits to the current turn only. Only supported by OpenAI GPT-5.6 and newer. |
| reasoning.effort | string | null | How much reasoning the model should spend. |
| reasoning.mode | string | null | Selects the reasoning mode. `standard` is the default; `pro` engages deeper reasoning on models that support it, billed at standard token rates. Only supported by OpenAI GPT-5.6 and newer. |
| reasoning.summary | string | null | How detailed the reasoning summary should be. |
| safety_identifier | string | null | End-user identifier the request supplied for abuse monitoring; null when none was set. |
| service_tier | string | null | Service tier the provider used for the response; null when not reported. |
| status | string | Lifecycle status of the response. |
| store | boolean | Whether the response is stored so it can be retrieved later. |
| temperature | number | null | Sampling temperature that applied to the request, if any. |
| text | object | Text output configuration including format and verbosity |
| text.format | object | Text response format configuration |
| text.verbosity | string | null | How long the answer should be. |
| tool_choice | string | object | How the model picks tools: a mode string or a specific tool. |
| tool_choice.name | string | Name of the function or tool the model must call. |
| tool_choice.type | string | Kind of tool the model must call. / Always `allowed_tools`. Discriminator that marks this object as a ToolChoiceAllowed in a `type`-tagged union. / Kind of tool the model must call. / Kind of tool the model must call. |
| tool_choice.mode | string | auto lets the model pick among the allowed tools or none; required forces a call to one of them. |
| tool_choice.tools | array<object> | The allowed tools, each as a tool reference such as {type: function, name}. |
| tools | array<object> | Tools that were available to the model for this response. |
| tools[].description | string | null | string | string | What the function does and when to use it; the model reads this to decide whether to call it. / What the custom tool does and when to use it. / What the group of tools is for. |
| tools[].name | string | Name of the function; the model uses it in function_call items. / Name of the custom tool. / Name of the namespace that groups the tools. |
| tools[].parameters | object | null | JSON Schema of the function arguments; null when the function takes none. |
| tools[].strict | boolean | null | Whether to enforce strict argument validation against the schema; null leaves the provider default. |
| tools[].type | string | Always `function`. Discriminator that marks this object as a FunctionTool in a `type`-tagged union. / Always `web_search_preview`. Discriminator that marks this object as a Preview_WebSearchServerTool in a `type`-tagged union. / Always `web_search_preview_2025_03_11`. Discriminator that marks this object as a Preview_20250311_WebSearchServerTool in a `type`-tagged union. / Always `web_search`. Discriminator that marks this object as a Legacy_WebSearchServerTool in a `type`-tagged union. / Always `web_search_2025_08_26`. Discriminator that marks this object as a WebSearchServerTool in a `type`-tagged union. / Comparison operator. / Always `computer_use_preview`. Discriminator that marks this object as a ComputerUseServerTool in a `type`-tagged union. / Always `code_interpreter`. Discriminator that marks this object as a CodeInterpreterServerTool in a `type`-tagged union. / Always `mcp`. Discriminator that marks this object as a McpServerTool in a `type`-tagged union. / Always `image_generation`. Discriminator that marks this object as a ImageGenerationServerTool in a `type`-tagged union. / Always `local_shell`. Discriminator that marks this object as a CodexLocalShellTool in a `type`-tagged union. / Always `shell`. Discriminator that marks this object as a ShellServerTool in a `type`-tagged union. / Always `apply_patch`. Discriminator that marks this object as a ApplyPatchServerTool in a `type`-tagged union. / Always `custom`. Discriminator that marks this object as a CustomTool in a `type`-tagged union. / Always `namespace`. Discriminator that marks this object as a NamespaceTool in a `type`-tagged union. |
| tools[].async | boolean | Lets the model keep working after calling this tool instead of waiting for its output. The tool is still executed by the client; return the result in a later request as a `function_call_output` with the original `call_id`. Only honored by providers whose Responses API supports async tools; ignored elsewhere. |
| tools[].defer_loading | boolean | Withhold this tool from the model until `openrouter:tool_search` finds it. Requires the tool search server tool; at least one tool must remain non-deferred. |
| tools[].engine | string | Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). |
| tools[].filters | object | null | Restricts web search by domain. / Attribute filter applied to the search: a comparison or a compound filter. |
| tools[].max_results | integer | Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped. |
| tools[].max_uses | integer | Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded only to Anthropic (as `max_uses`); other native search providers have no equivalent parameter and ignore it. |
| tools[].mode | string | Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored. |
| tools[].search_context_size | string | Size of the search context for web search tools |
| tools[].user_location | object | null | Approximate location of the user, used to bias web search results. / User location information for web search / User location information for web search |
| tools[].max_num_results | integer | Maximum number of results to return, between 1 and 50. |
| tools[].ranking_options | object | Ranking options for the search. |
| tools[].vector_store_ids | array<string> | Ids of the vector stores to search. |
| tools[].display_height | integer | Height of the computer display in pixels. |
| tools[].display_width | integer | Width of the computer display in pixels. |
| tools[].environment | string | Kind of environment that is controlled. |
| tools[].container | string | object | Container for the code to run in: a container id or an automatic container with files. |
| tools[].allowed_tools | array<string> | object | null | Tools of the server the model may use: a list of names or a filter. |
| tools[].authorization | string | OAuth access token for the MCP server. |
| tools[].connector_id | string | Id of a built-in connector; give this or server_url. |
| tools[].headers | object | null | HTTP headers sent to the MCP server; null for none. |
| tools[].require_approval | object | string | null | Whether tool calls need approval before they run: always, never, or a filter per tool. |
| tools[].server_description | string | What the MCP server is for, which helps the model decide when to use it. |
| tools[].server_label | string | Label that names the MCP server in the conversation. |
| tools[].server_url | string | URL of the MCP server; give this or connector_id. |
| tools[].background | string | Background of the generated image. |
| tools[].input_fidelity | string | null | How closely to preserve details of input images; null uses the default. |
| tools[].input_image_mask | object | Mask that marks the region of the input image to edit. |
| tools[].model | string | Image model to use. |
| tools[].moderation | string | Moderation level applied to the generated image. |
| tools[].output_compression | integer | Compression level from 0 to 100 for jpeg and webp output. |
| tools[].output_format | string | File format of the generated image. |
| tools[].partial_images | integer | Number of partial images to stream while generating, from 0 to 3. |
| tools[].quality | string | Quality of the generated image. |
| tools[].size | string | Size of the generated image; auto lets the model choose. |
| tools[].format | object | Format of the tool input: free text or a grammar. |
| tools[].tools | array<object> | Function tools in the namespace. |
| top_logprobs | integer | Number of most likely tokens whose log probabilities were requested per position. |
| top_p | number | null | Nucleus sampling value that applied to the request, if any. |
| truncation | string | null | How to handle input that exceeds the context window. |
| usage | object | null | Token usage information for the response |
| usage.input_tokens | integer | Number of input tokens, cached tokens included. |
| usage.input_tokens_details | object | Breakdown of the input tokens. |
| usage.output_tokens | integer | Number of output tokens, reasoning tokens included. |
| usage.output_tokens_details | object | Breakdown of the output tokens. |
| usage.total_tokens | integer | Input plus output tokens. |
| usage.cost | number | null | Cost of the completion |
| usage.cost_details | object | Breakdown of the upstream inference cost. |
| usage.is_byok | boolean | Whether a request was made using a Bring Your Own Key configuration |
| usage.server_tool_use_details | object | null | Usage for server-side tool execution (e.g., web search) |
| user | string | null | End-user identifier the request supplied; null when none was set. |
| error_type | string | Canonical OpenRouter error type, stable across all API formats |
| openrouter_metadata | object | Routing report: what was requested, how the router chose, and what was attempted. |
| openrouter_metadata.attempt | integer | Number of the attempt that served the request, starting at 1. |
| openrouter_metadata.attempts | array<object> | Every attempt that was made, in order. |
| openrouter_metadata.endpoints | object | Which endpoints were available and which one was chosen. |
| openrouter_metadata.generation_time | integer | Milliseconds measured for the generation, from dispatching the upstream request until its response body ended. Divide the completion token count by this for throughput. Absent when no upstream request was dispatched. |
| openrouter_metadata.is_byok | boolean | Whether the request used a key supplied by the caller. |
| openrouter_metadata.params | object | Router parameters that applied to the request. |
| openrouter_metadata.pipeline | array<object> | Stages the request went through before and after the model call. |
| openrouter_metadata.region | string | null | Region that served the request; null when unknown. |
| openrouter_metadata.requested | string | The model or alias the request asked for. |
| openrouter_metadata.strategy | string | How the router picked the model or provider for this request. |
| openrouter_metadata.summary | string | One-line summary of the routing decision. |
text/event-stream — chunk / 事件对象
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Optional id of the server-sent event. |
| event | string | Name of the server-sent event. |
| data | object | string | Payload of the server-sent event. |
| data.response | object | Complete non-streaming response from the Responses API |
| data.sequence_number | integer | Position of this event in the stream. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream. |
| data.type | string | Always `response.created`. Discriminator that marks this object as a CreatedEvent in a `type`-tagged union. / Always `response.in_progress`. Discriminator that marks this object as a InProgressEvent in a `type`-tagged union. / Always `response.completed`. Discriminator that marks this object as a CompletedEvent in a `type`-tagged union. / Always `response.incomplete`. Discriminator that marks this object as a IncompleteEvent in a `type`-tagged union. / Always `response.failed`. Discriminator that marks this object as a FailedEvent in a `type`-tagged union. / Always `error`. Discriminator that marks this object as a BaseErrorEvent in a `type`-tagged union. / Always `response.output_item.added`. Discriminator that marks this object as a OutputItemAddedEvent in a `type`-tagged union. / Always `response.output_item.done`. Discriminator that marks this object as a OutputItemDoneEvent in a `type`-tagged union. / Always `response.content_part.added`. Discriminator that marks this object as a BaseContentPartAddedEvent in a `type`-tagged union. / Always `response.content_part.done`. Discriminator that marks this object as a BaseContentPartDoneEvent in a `type`-tagged union. / Always `response.output_text.delta`. Discriminator that marks this object as a BaseTextDeltaEvent in a `type`-tagged union. / Always `response.output_text.done`. Discriminator that marks this object as a BaseTextDoneEvent in a `type`-tagged union. / Always `response.refusal.delta`. Discriminator that marks this object as a BaseRefusalDeltaEvent in a `type`-tagged union. / Always `response.refusal.done`. Discriminator that marks this object as a BaseRefusalDoneEvent in a `type`-tagged union. / Always `response.output_text.annotation.added`. Discriminator that marks this object as a BaseAnnotationAddedEvent in a `type`-tagged union. / Always `response.function_call_arguments.delta`. Discriminator that marks this object as a BaseFunctionCallArgsDeltaEvent in a `type`-tagged union. / Always `response.function_call_arguments.done`. Discriminator that marks this object as a BaseFunctionCallArgsDoneEvent in a `type`-tagged union. / Always `response.reasoning_text.delta`. Discriminator that marks this object as a BaseReasoningDeltaEvent in a `type`-tagged union. / Always `response.reasoning_text.done`. Discriminator that marks this object as a BaseReasoningDoneEvent in a `type`-tagged union. / Always `response.reasoning_summary_part.added`. Discriminator that marks this object as a BaseReasoningSummaryPartAddedEvent in a `type`-tagged union. / Always `response.reasoning_summary_part.done`. Discriminator that marks this object as a BaseReasoningSummaryPartDoneEvent in a `type`-tagged union. / Always `response.reasoning_summary_text.delta`. Discriminator that marks this object as a BaseReasoningSummaryTextDeltaEvent in a `type`-tagged union. / Always `response.reasoning_summary_text.done`. Discriminator that marks this object as a BaseReasoningSummaryTextDoneEvent in a `type`-tagged union. / Always `response.image_generation_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesImageGenCallInProgress in a `type`-tagged union. / Always `response.image_generation_call.generating`. Discriminator that marks this object as a OpenAIResponsesImageGenCallGenerating in a `type`-tagged union. / Always `response.image_generation_call.partial_image`. Discriminator that marks this object as a OpenAIResponsesImageGenCallPartialImage in a `type`-tagged union. / Always `response.image_generation_call.completed`. Discriminator that marks this object as a OpenAIResponsesImageGenCallCompleted in a `type`-tagged union. / Always `response.code_interpreter_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallInProgress in a `type`-tagged union. / Always `response.code_interpreter_call.interpreting`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallInterpreting in a `type`-tagged union. / Always `response.code_interpreter_call.completed`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCompleted in a `type`-tagged union. / Always `response.code_interpreter_call_code.delta`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCodeDelta in a `type`-tagged union. / Always `response.code_interpreter_call_code.done`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCodeDone in a `type`-tagged union. / Always `response.web_search_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesWebSearchCallInProgress in a `type`-tagged union. / Always `response.web_search_call.searching`. Discriminator that marks this object as a OpenAIResponsesWebSearchCallSearching in a `type`-tagged union. / Always `response.web_search_call.completed`. Discriminator that marks this object as a OpenAIResponsesSearchCompleted in a `type`-tagged union. / Always `response.custom_tool_call_input.delta`. Discriminator that marks this object as a BaseCustomToolCallInputDeltaEvent in a `type`-tagged union. / Always `response.custom_tool_call_input.done`. Discriminator that marks this object as a BaseCustomToolCallInputDoneEvent in a `type`-tagged union. / Always `response.apply_patch_call_operation_diff.delta`. Discriminator that marks this object as a ApplyPatchCallOperationDiffDeltaEvent in a `type`-tagged union. / Always `response.apply_patch_call_operation_diff.done`. Discriminator that marks this object as a ApplyPatchCallOperationDiffDoneEvent in a `type`-tagged union. / Always `response.fusion_call.in_progress`. Discriminator that marks this object as a FusionCallInProgressEvent in a `type`-tagged union. / Always `response.fusion_call.panel.added`. Discriminator that marks this object as a FusionCallPanelAddedEvent in a `type`-tagged union. / Always `response.fusion_call.panel.delta`. Discriminator that marks this object as a FusionCallPanelDeltaEvent in a `type`-tagged union. / Always `response.fusion_call.panel.reasoning.delta`. Discriminator that marks this object as a FusionCallPanelReasoningDeltaEvent in a `type`-tagged union. / Always `response.fusion_call.panel.completed`. Discriminator that marks this object as a FusionCallPanelCompletedEvent in a `type`-tagged union. / Always `response.fusion_call.panel.failed`. Discriminator that marks this object as a FusionCallPanelFailedEvent in a `type`-tagged union. / Always `response.fusion_call.analysis.in_progress`. Discriminator that marks this object as a FusionCallAnalysisInProgressEvent in a `type`-tagged union. / Always `response.fusion_call.analysis.completed`. Discriminator that marks this object as a FusionCallAnalysisCompletedEvent in a `type`-tagged union. / Always `response.fusion_call.completed`. Discriminator that marks this object as a FusionCallCompletedEvent in a `type`-tagged union. / Always `response.debug`. Discriminator that marks this object as a DebugEvent in a `type`-tagged union. |
| data.code | string | null | string | Error code; null when the upstream gave none. / The complete code the interpreter runs. |
| data.message | string | Human-readable error message. |
| data.param | string | null | Name of the request parameter the error is about; null when it is not about a parameter. |
| data.item | object | An output item from the response |
| data.output_index | integer | Index of the item in the response output array that this event belongs to. |
| data.content_index | integer | Index of the content part inside the output item that this event belongs to. |
| data.item_id | string | Id of the output item this event belongs to; it equals the id of that item in the response output. |
| data.part | object | The content part as it starts: output text or refusal. / The content part in its final form: output text or refusal. / A reasoning summary part. / A reasoning summary part. |
| data.delta | string | Text fragment to append to the output text of this content part. / Refusal text fragment to append. / Fragment of the JSON-encoded function arguments to append. / Reasoning text fragment to append. / Reasoning summary text fragment to append. / Fragment of the code the interpreter will run, to append. / Fragment of the custom tool call input to append. / Fragment of the patch diff to append. / Text fragment the panel model produced. / Reasoning text fragment the panel model produced. |
| data.logprobs | array<object> | Log probabilities of the tokens in this fragment, when requested. / Log probabilities of the tokens in the complete text, when requested. |
| data.text | string | The complete output text of this content part. / The complete reasoning text of this content part. / The complete reasoning summary text of this part. |
| data.refusal | string | The complete refusal text. |
| data.annotation | object | Annotation attached to output text: a file citation, URL citation or file path. |
| data.annotation_index | integer | Index of the new annotation inside the content part's annotations array. |
| data.arguments | string | The complete JSON-encoded arguments of the function call. |
| data.name | string | Name of the function being called. |
| data.summary_index | integer | Index of the reasoning summary part inside the reasoning item that this event belongs to. |
| data.partial_image_b64 | string | Base64-encoded partial image produced while generation is still running. |
| data.partial_image_index | integer | Zero-based index of this partial image among the partial images of the call. |
| data.input | string | The complete input of the custom tool call. |
| data.diff | string | The complete patch diff. |
| data.model | string | Slug of the panel model that started. / Slug of the panel model that produced the fragment. / Slug of the panel model that produced the fragment. / Slug of the panel model that finished. / Slug of the panel model that failed. |
| data.content | string | The complete answer of the panel model. |
| data.error | string | Error message that explains why the panel model failed. |
| data.status_code | integer | HTTP status code of the failed upstream call, when one is available. |
| data.analyst_model | string | Slug of the model producing the structured analysis. |
| data.judge_model | string | Deprecated alias of `analyst_model`, kept so existing consumers keep working. Always carries the same value. Use `analyst_model`. |
| data.analysis | object | Structured analysis produced by the fusion analyst model. |
| data.debug | object | Debug information. |
先调用「生成响应」，用返回的 ID 替换 resp_123。
/model/v1/responses/{response_id}● 支持response_idstring必填path: Id of the stored response, the `id` returned by createResponse (it looks like resp_...). An unknown id, a response created with store false, an expired response and another tenant's response all answer 404.
200 response
按 ID 读取一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，读取会返回 404 response_not_found；超过保留期（默认 30 天）后读取也会返回同样的 404。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
先调用「生成响应」，用返回的 ID 替换 resp_123。
/model/v1/responses/{response_id}● 支持response_idstring必填path: Id of the stored response, the `id` returned by createResponse (it looks like resp_...). An unknown id, a response created with store false, an expired response and another tenant's response all answer 404.
200 response
按 ID 立即删除一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，删除会返回 404 response_not_found。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API delete response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
先调用「生成响应」，用返回的 ID 替换 resp_123。
/model/v1/responses/{response_id}/cancel◐ 部分支持response_idstring必填path: Id of the stored response, the `id` returned by createResponse (it looks like resp_...). An unknown id, a response created with store false, an expired response and another tenant's response all answer 404.
200 response
仅对以 background:true 创建、且路由到具备后台生成能力的模型的响应可用：取消是 幂等的，重复调用返回同一个终态响应；我方的取消只能停止我方对上游流的继续读取， 不能保证已发往上游的算力停止计算，用量按实际收到的部分结算。对一个非后台 （同步）响应调用 cancel：如果这个响应 id 不存在（未持久化、已过期或 id 有误）， 返回 404 object_not_found；如果响应存在但其来源 provider 没有声明支持 cancel 操作（我们目前没有接入任何为同步响应声明该能力的上游），返回 400 native_responses_operation_unsupported。这两种情况都不是尚未实现的 501 gate。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API cancel response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
先调用「生成响应」，用返回的 ID 替换 resp_123。
/model/v1/responses/{response_id}/input_items● 支持response_idstring必填path: Id of the stored response, the `id` returned by createResponse (it looks like resp_...). An unknown id, a response created with store false, an expired response and another tenant's response all answer 404.
200 list
列出一条已保存响应的输入项。支持 limit（1–100，默认 20）、order（asc/desc， 默认 desc，与官方一致）与基于条目 id 的 after 游标分页；has_more/first_id/ last_id 均与实际返回页一致，可据此翻页且不重不漏。每个条目都带服务端签发的 id（message 为 msg_ 前缀，function_call/function_call_output/reasoning 各自 对应前缀），本次上线前已保存、尚无服务端 id 的旧数据在读取时按确定性规则补 id，不做破坏性迁移，同一游标反复读取保持稳定。以 previous_response_id 续接 创建的响应，其输入项列出解析后的完整输入：前序响应链已有的输入与输出条目 再加本轮自己提交的输入；若该祖先响应在我方平台未保存（例如创建时 store 为 false）或已过期删除，则只列出本轮自己提交的输入。如果创建时 store 为 false，我们不会保存这次响应，列出会返回 404 response_not_found。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API input item list
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
/model/v1/responses/compact○ 未支持501 平台还没有实现这个端点；调用会得到下面这个响应：
把响应的输入压缩成摘要，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API compact response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
/model/v1/responses/input_tokens○ 未支持501 平台还没有实现这个端点；调用会得到下面这个响应：
只统计请求输入会消耗的 token 数、不生成内容，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Native Responses API input token count
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
/model/v1/embeddings● 支持modelstring必填The model to use for embeddings
已验证生效。
inputstring | array必填◐ 部分支持Text, token, or multimodal input(s) to embed
文本及文本数组生效；token 整数数组返回 400。图片仅 qwen3-vl-embedding、doubao-embedding-vision 支持；text-embedding-3-small 的 16 条批量返回 400。
dimensionsinteger可选◐ 部分支持The number of dimensions for the output embeddings
仅 text-embedding-3-small、qwen3-vl-embedding 支持已测的 256 维；text-embedding-3-small 也支持 512，100 返回 400。bge-m3、qwen3-embedding-0.6b、doubao-embedding-vision 的 256 维返回 400。
encoding_formatstring可选The format of the output embeddings
float 与 base64 均支持；base64 为向量的二进制编码。
input_typestring可选◐ 部分支持The type of input (e.g. search_query, search_document)
query/document 在 bge-m3、qwen3-embedding-0.6b 生效；search_query 返回 400；text-embedding-3-small 接受但当前不生效。
providerobject可选◐ 部分支持OpenRouter-style provider preferences, accepted for compatibility. Router support (partial): bge-m3 and qwen3-embedding-0.6b return 400; text-embedding-3-small accepts it, with an unobservable effect.
bge-m3、qwen3-embedding-0.6b 返回 400；text-embedding-3-small 接受，但效果不可观测。
allow_fallbacksboolean可选Whether to allow backup providers to serve requests - true: (default) when the primary provider (or your custom providers in "order") is unavailable, use the next best provider. - false: use only the primary/custom provider, and return the upstream error if it's unavailable.
data_collectionstring可选Data collection setting. If no available model provider meets the requirement, your request will return an error. - allow: (default) allow providers which store user data non-transiently and may train on it - deny: use only providers which do not collect user data.
enforce_distillable_textboolean可选Whether to restrict routing to only models that allow text distillation. When true, only models where the author has allowed distillation will be used.
ignorearray可选List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request.
max_priceobject可选The object specifying the maximum price you want to pay for this request. USD price per million tokens, for prompt and completion.
onlyarray可选List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request.
orderarray可选An ordered list of provider slugs. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message.
preferred_max_latencynumber | object可选Preferred maximum latency (in seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints above the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold.
preferred_min_throughputnumber | object可选Preferred minimum throughput (in tokens per second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints below the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold.
quantizationsarray可选A list of quantization levels to filter the provider by.
require_parametersboolean可选Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest.
sortstring | object可选The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed.
zdrboolean可选Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used.
session_idstring可选◐ 部分支持A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.
bge-m3、qwen3-embedding-0.6b 返回 400；text-embedding-3-small 接受，但效果不可观测。
traceobject可选◐ 部分支持Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.
bge-m3、qwen3-embedding-0.6b 返回 400；text-embedding-3-small 接受，但效果不可观测。
generation_namestring可选Name of this generation in the trace.
parent_span_idstring可选Id of the parent span in the trace.
span_namestring可选Name of this request's span in the trace.
trace_idstring可选Id that groups several requests into one trace.
trace_namestring可选Name of the trace.
userstring可选◐ 部分支持A unique identifier for the end-user
bge-m3、qwen3-embedding-0.6b 返回 400；text-embedding-3-small 接受，但效果不可观测。
200 list
未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Embedding response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| data | array<object> | List of embedding objects |
| data[].embedding | array<number> | string | Embedding vector as an array of floats or a base64 string |
| data[].index | integer | Index of the embedding in the input list |
| data[].object | string | Object type of the entry; always `embedding`. |
| id | string | Unique identifier for the embeddings response |
| model | string | The model used for embeddings |
| object | string | Object type; always `list`. |
| usage | object | Token usage statistics |
| usage.cost | number | Cost of the request in credits |
| usage.cost_details | object | null | Breakdown of upstream inference costs |
| usage.is_byok | boolean | Whether a request was made using a Bring Your Own Key configuration |
| usage.prompt_tokens | integer | Number of tokens in the input |
| usage.prompt_tokens_details | object | Per-modality token breakdown. Only present when the input contains 2+ modalities (e.g. text + image) and the upstream provider returns modality-level usage data. Only non-zero modality counts are included. |
| usage.total_tokens | integer | Total number of tokens used |
text/event-stream — chunk / 事件对象
○ 未支持
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Optional id of the server-sent event. |
| event | string | Name of the server-sent event. |
| data | string | Payload of the server-sent event. |
/model/v1/rerank● 支持modelstring必填Rerank model id; list candidates with listModels?type=reranking. Router support (supported): Verified to take effect.
已验证生效。
querystring必填Query to rank the documents against, at least 1 character. Router support (supported): Verified to take effect.
已验证生效。
documentsarray必填◐ 部分支持Documents to rank, as plain strings, at least one. Router support (partial): Only string arrays are supported; object arrays return 400.
只支持字符串数组；对象数组返回 400。
top_ninteger可选Number of best results to return, at least 1; omit it to return every document. Router support (supported): Controls returned result count; zero returns 400.
控制返回条数；0 返回 400。
return_documentsboolean可选○ 未支持bge-reranker-base 返回 400；只支持 model、query、documents、top_n。
max_tokens_per_docinteger可选○ 未支持bge-reranker-base 返回 400；只支持 model、query、documents、top_n。
rank_fieldsarray可选○ 未支持bge-reranker-base 返回 400；只支持 model、query、documents、top_n。
max_chunks_per_docinteger可选○ 未支持bge-reranker-base 返回 400；只支持 model、query、documents、top_n。
userstring可选○ 未支持bge-reranker-base 返回 400；只支持 model、query、documents、top_n。
200
标准请求字段；不能表达的参数返回 input_not_representable。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Cohere v2 rerank results.
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| results | array<object> | Results ordered by relevance, best first. Each entry points back to a document with `index`. |
| results[].index | integer | Zero-based position of the document in the request `documents` array. |
| results[].relevance_score | number | Relevance of the document to the query, from 0 to 1; larger is more relevant. |
/model/v1/audio/speech● 支持modelstring必填Speech model id, for example `melotts` or `aura-2-en`; list candidates with listModels?type=speech. Router support (supported): Verified to take effect.
已验证生效。
inputstring可选Text to synthesize, 1 to 4096 characters. `text` and `prompt` are aliases; when several are given, `input` wins. Router support (supported): melotts supports input, lang and response_format=wav; text/prompt aliases also work.
melotts 支持 input、lang、response_format=wav；也可用 text/prompt 别名。
response_formatstring可选◐ 部分支持MeloTTS supports only wav (default); all other explicit formats return 400. When omitted the actual upstream format is returned. Aura defaults to mp3; aac returns 400.
melotts 仅 WAV。aura-2-en 支持 mp3/opus/flac/wav/pcm；aac 报错。
promptstring可选MeloTTS alias for input; input then text take precedence.
input 的别名，input 优先。
voicestring | object可选◐ 部分支持Aura speaker name; custom voice objects are rejected by Aura. MeloTTS ignores voice with a warning unless provider.require_parameters is true, in which case it returns 400.
仅 aura-2-en 支持原生说话人名，如 thalia/apollo/orion/luna/zeus；不支持 alloy 或对象。melotts 必须省略。
idstring必填Id of a custom voice. Custom voice objects are not supported by these models and answer 400; use the string form of `voice` with an Aura speaker name.
instructionsstring可选○ 未支持Accepted by the protocol; these Cloudflare models reject it with 400.
melotts、aura-2-en 均返回 400。
speednumber可选◐ 部分支持Only 1 is representable by these Cloudflare models.
只接受默认值 1；非默认速度不支持，返回错误。
stream_formatstring可选◐ 部分支持Only audio is supported; the response is buffered binary audio.
audio 生效；sse 返回 400。
textstring可选Native alias for input; input wins.
input 的别名，input 优先。
speakerstring可选◐ 部分支持Aura alias for voice; voice wins.
aura-2-en 支持原生说话人名；melotts 返回 400。
langstring可选◐ 部分支持MeloTTS language; defaults to en. Use this field to select language; voice is not supported by MeloTTS.
melotts 支持 en/fr/es/zh；ja/ko 报错。aura-2-en 不支持 lang。
encodingstring可选◐ 部分支持Aura native encoding; response_format wins; mulaw/alaw/aac return 400 when used to select the format.
melotts 仅 linear16；aura-2-en 支持 linear16/flac 等已测编码，mulaw 返回 400；response_format 优先。
containerstring可选◐ 部分支持Aura container; response_format wins.
aura-2-en 支持 opus+ogg、linear16+none；container=wav 返回 400。melotts 不支持此字段。
sample_rateinteger可选◐ 部分支持Aura WAV supports 8000/16000/24000/32000/48000; FLAC supports 8000/16000/22050/32000/48000; PCM requires 24000; other formats reject this control.
仅 aura-2-en；wav 已测 8000/16000、pcm 已测 24000；44100 或 mp3 自定义采样率报错。melotts 不支持。
bit_rateinteger可选◐ 部分支持Aura bit rate in bits per second. MP3 supports 32000/48000; Opus supports 4000–650000. Other accepted formats reject this control.
仅 aura-2-en：mp3 已测 32000/48000、opus 已测 64000；mp3=64000 报错。melotts 不支持。
200
melotts 输出 WAV，只支持 input（含 text/prompt 别名）、lang 和默认音频选项；aura-2-en 使用原生 speaker 名称。逐字段限制见参数表。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Audio bytes in the requested format.
audio/mpeg
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
audio/ogg
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
audio/aac
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
audio/flac
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
audio/wav
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
audio/pcm
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
响应体为音频字节；右侧描述对象仅记录实采的 Content-Type 和字节数。
/model/v1/audio/transcriptions● 支持modelstring必填Transcription model id, for example `whisper-large-v3-turbo` or `qwen3-asr-flash`; list candidates with listModels?type=transcription. Router support (supported): Verified to take effect.
已验证生效。
temperaturenumber可选○ 未支持whisper-large-v3-turbo、qwen3-asr-flash 均返回 400。
response_formatstring可选◐ 部分支持Format of the response body. `json` and `text` are the commonly supported formats. Router support (partial): json/text work on both; verbose_json works only on whisper-large-v3-turbo. srt/vtt return 400.
json/text 均生效；verbose_json 仅 whisper-large-v3-turbo 支持。srt/vtt 均返回 400。
promptstring可选◐ 部分支持Text that primes the model with vocabulary or context. Router support (partial): Vocabulary hints work on whisper-large-v3-turbo only; qwen3-asr-flash returns 400.
仅 whisper-large-v3-turbo 的词表提示已验证生效；qwen3-asr-flash 返回 400。
filestring必填Audio file to transcribe, uploaded as multipart/form-data. Router support (supported): Verified to take effect.
已验证生效。
languagestring可选◐ 部分支持Language of the audio as an ISO-639-1 code such as `en` or `zh`. Router support (partial): Both models accept ISO language codes. qwen3-asr-flash may translate output to that language; whisper-large-v3-turbo treats it as an input hint. Non-ISO names may return 502.
两模型接受 ISO 语言码；qwen3-asr-flash 可能按指定语言翻译输出，whisper-large-v3-turbo 用作输入语言提示。非 ISO 名称可能报 502。
timestamp_granularities[]array可选◐ 部分支持Timestamp levels to include with `verbose_json`; only `segment` exists in this schema. Router support (partial): Only whisper-large-v3-turbo supports segment with verbose_json. word returns 400; qwen3-asr-flash does not support timestamps.
仅 whisper-large-v3-turbo 在 verbose_json 下支持 segment；word 返回 400；qwen3-asr-flash 不支持时间戳。
200
标准请求字段；不能表达的参数返回 input_not_representable。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Transcription in the requested format.
text/plain
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string |
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| text | string | The transcribed text. |
| task | string | Task performed; always `transcribe`. |
| language | string | Language of the audio as detected or as requested. |
| duration | number | Duration of the audio in seconds. |
| segments | array<object> | Segments with timestamps, returned with `verbose_json` on models that support it. |
| segments[].id | integer | Zero-based index of the segment. |
| segments[].start | number | Start time of the segment in seconds. |
| segments[].end | number | End time of the segment in seconds. |
| segments[].text | string | The transcribed text. |
| segments[].temperature | number | Sampling temperature used for the segment. |
| segments[].avg_logprob | number | Average log probability of the tokens of the segment; low values mean low confidence. |
| segments[].compression_ratio | number | Gzip compression ratio of the segment text; high values indicate repetitive output. |
| segments[].no_speech_prob | number | Probability that the segment contains no speech. |
/model/v1/images/generations● 支持modelstring必填Image model id; list candidates with listModels?type=image. Router support (supported): Verified to take effect.
已验证生效。
response_formatstring可选◐ 部分支持Image response encoding. Only b64_json is accepted; url returns 400.
gpt-image-2 支持 b64_json；url 返回 400。
promptstring必填Text description of the image to generate. Router support (supported): Verified to take effect.
已验证生效。
ninteger可选Number of images to generate, from 1 to 10; defaults to 1. Router support (supported): Controls image count; zero returns 400 and values 1–10 are accepted.
控制图片数量，0 返回 400，允许 1–10。
sizestring可选◐ 部分支持Size of the generated images. Router support (partial): gpt-image-2 supports tested 1024x1024 and 1024x1536 sizes; 512x512 returns 400.
gpt-image-2 已验证 1024x1024、1024x1536；512x512 返回 400。
qualitystring可选Quality of the generated images. Router support (supported): Verified to take effect.
已验证生效。
backgroundstring可选gpt-image-2 的 transparent 返回透明 PNG。
output_formatstring可选gpt-image-2 的 jpeg 返回 JPEG。
200
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Image generation response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| created | integer | Unix time in seconds at which the images were created. |
| data | array<object> | Generated images. |
| data[].url | string | URL of the image; present when response_format is `url`. |
| data[].b64_json | string | Base64-encoded image; present when response_format is `b64_json`. |
| data[].revised_prompt | string | Prompt after the image model rewrote it, when the model reports it. |
/model/v1/images/edits● 支持modelstring必填Image model id; list candidates with listModels?type=image. Router support (supported): Verified to take effect.
已验证生效。
promptstring必填Text description of the desired edit. Router support (supported): Verified to take effect.
已验证生效。
imagearray必填Source images as base64 data URLs.
maskstring可选○ 未支持Mask that marks the region to edit, as a base64 data URL or multipart file. Router support (unsupported): The tested PNG mask returns 400 and is currently unusable.
已测 PNG mask 返回 400；当前不可用。
nnumber可选Number of edited images to generate. Router support (supported): Verified to take effect.
已验证生效。
sizestring可选Size of the edited images. Router support (supported): Verified to take effect.
已验证生效。
image[]array可选Source images, uploaded as multipart files. Router support (supported): Accepts multipart files or JSON data URLs.
支持 multipart 文件或 JSON data URL。
200
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Edited images
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| created | number | Unix time in seconds at which the images were created. |
| data | array<object> | Edited images. |
| data[].url | string | URL of the image; present when response_format is `url`. |
| data[].b64_json | string | Base64-encoded image; present when response_format is `b64_json`. |
/model/v1/ocr● 支持modelstring必填OCR model ID, for example glm-ocr.
已验证生效。
documentobject必填Choose document_url, image_url (HTTPS or data URL), or {type: file, file_id: string}.
支持 PDF data URL、image_url 和已上传文件的 file_id；远端 URL 需可下载。
typestring必填Always `file`. Discriminator of the `type`-tagged union this object belongs to.
document_urlstring必填HTTPS or base64 data URL; required when type is document_url.
document_namestring可选Optional file name of the document, used by the provider for display.
image_urlstring必填HTTPS or base64 data URL; required when type is image_url.
file_idstring必填File ID owned by the authenticated tenant. The file_id read limit is 24 MiB (25165824 bytes; shared 96 MiB memory budget / 4); PNG/JPEG remain limited to 10 MiB. Larger files return 413: use HTTPS document_url for PDFs up to 50 MiB. Image pages must be [0].
pagesarray可选Zero-based page indices to process.
零起始页码，可选择多页并去重；越界页会报错。
include_image_base64boolean可选◐ 部分支持Include extracted images as base64.
glm-ocr 仅接受 false；true 返回 400。
table_formatstring可选◐ 部分支持Format for tables that are extracted separately: when set, tables come back in `tables` in this format and the page markdown keeps a link to each; when null they stay inline in the markdown. Router support (partial): glm-ocr accepts markdown or null only; html returns 400.
glm-ocr 仅接受 markdown 或 null；html 返回 400。
extract_headerboolean可选○ 未支持Whether to extract page headers separately into `header`. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
extract_footerboolean可选○ 未支持Whether to extract page footers separately into `footer`. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
bbox_annotation_formatobject可选○ 未支持Structured image annotations; OCR requires json_schema. Availability depends on the model.
glm-ocr 不支持，传入返回 400。
typestring可选Response format type of the annotation.
json_schemaobject可选JSON Schema the annotation of each detected image region must follow.
document_annotation_formatobject可选○ 未支持Structured document annotation; OCR requires json_schema. Availability depends on the model.
glm-ocr 不支持，传入返回 400。
typestring可选Response format type of the annotation.
json_schemaobject可选JSON Schema the document annotation must follow.
document_annotation_promptstring可选○ 未支持Instruction for the document annotation, which says what to extract. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
image_limitinteger可选○ 未支持Maximum number of images to extract per document; null for no limit. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
image_min_sizeinteger可选○ 未支持Minimum height and width in pixels of images to extract; null for no minimum. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
include_blocksboolean可选○ 未支持Whether to return layout `blocks` for each page. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
confidence_scores_granularitystring可选○ 未支持Level at which confidence scores are returned. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.
glm-ocr 不支持，传入返回 400。
200
采用 Mistral OCR 请求与响应形状，仅提供 /model/v1/ocr。model 必填；document 接受 document_url 或 image_url（HTTPS 或 base64 data URL），也接受 `{type:"file", file_id:"<上传所得 ID>"}`，直接读取当前租户的 File。file_id 读取上限为 24 MiB（25,165,824 字节，共享 96 MiB 内存预算按四倍预留）；超过此上限返回 413，并提示改用 HTTPS document_url（PDF 上限 50 MiB）。PNG/JPEG 仍限 10 MiB，按文件头识别类型；不存在或其他租户的文件统一返回 404。pages 是从 0 开始的页码数组；图片如指定 pages，只能为 `[0]`。文件读取失败不计费，请求日志仅记录 file_id，不保存文件原文。可选功能依模型而定，不支持的选项返回 400。错误为 problem+json；providerOptions.praxis 不适用于此端点。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
OCR pages and usage
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| pages | array<object> | Result per processed page, in page order. |
| pages[].index | integer | Zero-based index of the page in the document. |
| pages[].markdown | string | Page content as markdown. |
| pages[].images | array<object> | Images found on the page. |
| pages[].dimensions | object | null | Size of the rendered page; null when unknown. |
| pages[].tables | array<object> | Tables extracted from the page when table_format is set. |
| pages[].hyperlinks | array<string> | Hyperlinks found on the page. |
| pages[].header | string | null | Page header text; null when none was extracted. |
| pages[].footer | string | null | Page footer text; null when none was extracted. |
| pages[].blocks | array<object> | null | Layout blocks of the page, in reading order, when include_blocks is true. |
| pages[].confidence_scores | object | null | Confidence scores of the page; null when not requested. |
| model | string | OCR model that processed the document. |
| usage_info | object | Usage of the request. |
| usage_info.pages_processed | integer | Number of pages that were processed. |
| usage_info.doc_size_bytes | integer | null | Size of the document in bytes; null when unknown. |
| document_annotation | string | null | Document annotation as a JSON string, when document_annotation_format was requested; null otherwise. |
/model/v1/videos● 支持modelstring可选◐ 部分支持Video model id, for example `wan2.7-t2v`; list candidates with listModels?type=video. Router support (partial): Select a registered video model explicitly, for example wan2.7-t2v (size=1280x720, seconds=4). Capability preflight errors are reported before creation.
请显式选择已注册的视频模型，例如 wan2.7-t2v（size=1280x720，seconds=4）。能力预检失败会在创建前报错。
promptstring必填Text description of the video, at least 1 character. Router support (supported): Controls video content; missing or empty values return 400.
控制视频内容；缺失或空值返回 400。
secondsstring | integer可选同时提供时优先于 duration。
已验证 wan2.7-t2v 的时长生效；不合法或超出模型能力的值在预检阶段返回 400。
durationinteger可选Length of the video in whole seconds. `seconds` takes precedence when both are given.
sizestring可选◐ 部分支持Output resolution as `WIDTHxHEIGHT`, for example `1280x720`. Router support (partial): Subject to model capability preflight. Earlier wan2.7-t2v samples always produced 1280x720; accepted sizes are not guaranteed pixel-for-pixel.
受模型能力预检限制；早期 wan2.7-t2v 样本始终输出 1280x720，不保证所有接受的尺寸都会按像素兑现。
input_referencestring | object可选Reference image for image-to-video: a URL or base64 data URL, an object with `image_url`, or an uploaded image file (multipart, at most 20 MiB).
image_urlstring | object必填URL or base64 data URL of the reference image, as a string or an object with `url`.
input_referencesarray可选Several reference images; each entry is a URL or base64 data URL, or an object with `image_url`.
image_urlstring | object可选URL or base64 data URL of the reference image, as a string or an object with `url`.
frame_imagesarray可选Images that pin the first and last frame; at most 2 entries.
typeany可选Always `image_url`. Discriminator of the `type`-tagged union this object belongs to.
frame_typeany必填Frame to constrain with the supplied image: first_frame or last_frame. Each frame type may occur at most once.
image_urlobject必填The image to pin.
resolutionstring可选Output resolution label such as `720p`, for models that take a label instead of `size`.
aspect_ratiostring可选Aspect ratio of the video such as `16:9`.
generate_audioboolean可选Whether the video carries a generated audio track. Router support (supported): false produces no audio track on wan2.7-t2v; the default output includes audio.
wan2.7-t2v 的 false 输出无音轨，默认输出含音轨。
seedinteger可选Seed for reproducible generation, on models that support it.
callback_urlstring可选HTTP or HTTPS callback URL, forwarded to models that support completion callbacks.
qualitystring可选Provider-specific quality setting.
200
按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Success
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| object | string | Object type; always `video`. |
| model | string | Model that generates the video. |
| status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| created_at | integer | Unix time in seconds at which the job was created. |
| completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| prompt | string | null | Prompt the job was created with. |
| remixed_from_video_id | null | Always null; remix is not supported. |
| error | object | null | Why the job failed; null unless status is `failed`. |
| error.code | string | Machine-readable failure code. |
| error.message | string | Human-readable failure message. |
| polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| usage | object | Cost of the job; present once a price applies. |
| usage.cost | number | Cost of the job in USD: delivered seconds times the per-second price once completed, 0 while running. |
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
典型耗时为 10–15 分钟；以下示例最多轮询 30 分钟，超时后可用同一个任务 ID 继续查询。
# Requires curl and jq. Set PRAXIS_API_KEY and API_BASE (your API origin).
job=$(curl --fail-with-body -sS "$API_BASE/model/v1/videos" \
-H "Authorization: Bearer $PRAXIS_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"wan2.7-t2v","prompt":"A cat stretching in the morning sun","seconds":"4","size":"1280x720"}') || exit 1
VIDEO_ID=$(printf '%s' "$job" | jq -er '.id') || exit 1
for attempt in $(seq 1 360); do
job=$(curl --fail-with-body -sS "$API_BASE/model/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $PRAXIS_API_KEY") || exit 1
status=$(printf '%s' "$job" | jq -er '.status') || exit 1
case "$status" in
completed) break ;;
failed) printf '%s\n' "$job"; exit 1 ;;
queued|in_progress) sleep 5 ;;
*) printf 'Unexpected status: %s\n' "$status"; exit 1 ;;
esac
done
[ "$status" = completed ] || { printf 'Still processing; resume polling %s\n' "$VIDEO_ID"; exit 1; }
curl --fail-with-body -sS "$API_BASE/model/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $PRAXIS_API_KEY" -o video.mp4/model/v1/videos● 支持afterstring可选query: Cursor: the id of the video job after which the page starts, normally the `last_id` of the previous page. It must refer to an existing job of yours, otherwise the call fails.
分页参数生效；limit 为 1–100，order 为 asc/desc，after 必须引用存在的任务。
limitinteger可选query: Maximum number of jobs per page, from 1 to 100; defaults to 20.
分页参数生效；limit 为 1–100，order 为 asc/desc，after 必须引用存在的任务。
orderany可选query: Sort order by creation time: desc (default) lists the newest job first, asc the oldest first.
分页参数生效；limit 为 1–100，order 为 asc/desc，after 必须引用存在的任务。
200
按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Success
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `list`. |
| data | array<object> | Video jobs of the caller, newest first by default. |
| data[].id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| data[].object | string | Object type; always `video`. |
| data[].model | string | Model that generates the video. |
| data[].status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| data[].progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| data[].created_at | integer | Unix time in seconds at which the job was created. |
| data[].completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| data[].expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| data[].seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| data[].size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| data[].prompt | string | null | Prompt the job was created with. |
| data[].remixed_from_video_id | null | Always null; remix is not supported. |
| data[].error | object | null | Why the job failed; null unless status is `failed`. |
| data[].polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| data[].unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| data[].usage | object | Cost of the job; present once a price applies. |
| has_more | boolean | Whether more jobs exist beyond this page; pass `last_id` as `after` to read them. |
| first_id | string | null | Id of the first job in this page; null for an empty page. |
| last_id | string | null | Id of the last job in this page; null for an empty page. |
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
先调用「创建视频」，用返回的 ID 替换 video_123；下载前须轮询至 completed。
/model/v1/videos/{video_id}● 支持video_idstring必填path: Id of the video job whose output you want, the `id` returned by createVideo. The job must be completed; before that the call answers 400.
200
按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Success
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| object | string | Object type; always `video`. |
| model | string | Model that generates the video. |
| status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| created_at | integer | Unix time in seconds at which the job was created. |
| completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| prompt | string | null | Prompt the job was created with. |
| remixed_from_video_id | null | Always null; remix is not supported. |
| error | object | null | Why the job failed; null unless status is `failed`. |
| error.code | string | Machine-readable failure code. |
| error.message | string | Human-readable failure message. |
| polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| usage | object | Cost of the job; present once a price applies. |
| usage.cost | number | Cost of the job in USD: delivered seconds times the per-second price once completed, 0 while running. |
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
先调用「创建视频」，用返回的 ID 替换 video_123；下载前须轮询至 completed。
/model/v1/videos/{video_id}/content● 支持video_idstring必填path: Id of the video job whose output you want, the `id` returned by createVideo. The job must be completed; before that the call answers 400.
variantany可选◐ 部分支持query: Spritesheet is not available in this release (400).
video、thumbnail 生效；spritesheet 返回 400。
indexinteger可选◐ 部分支持query: Output index; this release produces index 0. variant takes precedence.
视频仅支持 index=0；大于 0 或负数返回 400。variant=thumbnail 时 index 接受但当前不生效。
200
按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Video or thumbnail bytes
video/mp4
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
image/jpeg
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | string (binary) |
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
先调用「创建视频」，用返回的 ID 替换 video_123；下载前须轮询至 completed。
/model/v1/videos/{video_id}● 支持video_idstring必填path: Id of the video job whose output you want, the `id` returned by createVideo. The job must be completed; before that the call answers 400.
200
按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Success
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the deleted video job. |
| object | string | Object type; always `video.deleted`. |
| deleted | boolean | Always true; the job is no longer readable. |
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
先调用「创建视频」，用返回的 ID 替换 video_123；下载前须轮询至 completed。
/model/v1/videos/{video_id}/remix○ 未支持video_idstring必填path: Id of the video job whose output you want, the `id` returned by createVideo. The job must be completed; before that the call answers 400.
400 混剪尚未支持，请勿重试。
未支持，调用返回 400；不要重试。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
此端点没有声明成功响应。
先创建视频，保存返回的 id；再读取视频轮询 status，queued / in_progress 时继续等待，failed 时停止并查看 error；只有 completed 后才下载视频内容。
/model/v1/messages● 支持modelstring必填◐ 部分支持Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
deepseek-v4-pro、glm-5.3-flash、qwen3.8-flash、claude-opus-5 可调用；deepseek-v4-flash 在此协议面返回 400。
messagesarray必填◐ 部分支持Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.
文本和工具往返生效；document 的托管 file_id 返回 400，qwen3.8-flash 可读取内联 PDF；图片有模型尺寸限制。
contentstring | array必填Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.
rolestring必填Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.
max_tokensnumber必填Body param: The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
限制输出 token，思考也占用预算。
streamboolean可选◐ 部分支持Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) for details.
流式正文和工具事件可用；可能在正文前出现额外 message_delta，message_start 的用量为 0。
systemstring | array可选Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
已验证生效。
temperaturenumber可选Sampling temperature between 0 and 1; defaults are model specific.
top_pnumber可选Nucleus sampling: only tokens within this cumulative probability are considered.
toolsarray可选Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
已验证生效。
tool_choiceobject可选◐ 部分支持Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
qwen3.8-flash 四种模式生效；deepseek-v4-pro 忽略 any/tool/none；glm-5.3-flash 忽略 none。
typestring必填Disable tool calls for this request.
disable_parallel_tool_useboolean可选○ 当前不生效Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.
接受但当前不生效。true 仍可能返回多个工具调用。
namestring必填The name of the tool to use.
cache_controlobject可选◐ 部分支持Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
deepseek-v4-pro、qwen3.8-flash、glm-5.3-flash 有隐式缓存命中，但不能据此确认标记生效；claude-opus-5 未命中缓存，ttl=1h 未见效果。
typestring必填Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.
ttlstring可选The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
containerstring | object可选○ 当前不生效接受并忽略 container；平台尚未实现此能力。
idstring可选Container id
skillsarray可选List of skills to load in the container
inference_geostring可选○ 当前不生效接受并忽略 inference_geo；平台尚未实现此能力。
metadataobject可选◐ 部分支持Body param: An object describing metadata about the request.
接受 metadata；metadata.user_id 由同协议线路传递，不承诺上游回显。
user_idstring可选An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.
output_configobject可选Body param: Configuration options for the model's output, such as the output format.
effortstring可选◐ 部分支持All possible effort levels.
deepseek-v4-pro 仅 high/xhigh 可用，其余返回 400；qwen3.8-flash 全档返回 400；glm-5.3-flash 接受各档但消耗不随档位单调变化。
formatobject可选◐ 部分支持A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
json_schema 在 deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 与 thinking 同传返回 400。
service_tierstring可选○ 当前不生效接受并忽略 service_tier；平台尚未实现此能力。
stop_sequencesarray可选◐ 部分支持Body param: Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence.
deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 文本截断但 stop_reason 和 stop_sequence 未准确反映。
thinkingobject可选◐ 部分支持Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
disabled 在 deepseek-v4-pro、qwen3.8-flash 生效；glm-5.3-flash 携带任何 thinking 都返回 400。adaptive 在已测的 deepseek-v4-pro、qwen3.8-flash 也返回 400。
budget_tokensnumber必填◐ 部分支持Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
deepseek-v4-pro、qwen3.8-flash 接受，但预算不构成可靠上限；glm-5.3-flash 返回 400。
typestring必填Let the model choose its reasoning budget, subject to output_config.effort when supplied.
displaystring可选○ 当前不生效Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
接受但当前不生效。omitted 仍返回完整思考内容。
top_knumber可选Sample only from the top K options for each token.
context_managementobject可选○ 当前不生效接受并忽略 context_management；平台尚未实现此能力。
diagnosticsobject可选○ 当前不生效接受并忽略 diagnostics；平台尚未实现此能力。
mcp_serversarray可选○ 当前不生效接受并忽略 mcp_servers；平台尚未实现此能力。
speedstring可选○ 当前不生效接受并忽略 speed；平台尚未实现此能力。
output_formatobject可选○ 当前不生效接受并忽略此旧字段；结构化输出使用 output_config.format。
compactionobject可选○ 未支持已识别 compaction；尚未实现，传入返回 400 并明确说明不支持。
fallback_credit_tokenstring可选○ 未支持已识别 fallback_credit_token；尚未实现，传入返回 400 并明确说明不支持。
fallbacksstring可选○ 未支持已识别 fallbacks；尚未实现，传入返回 400 并明确说明不支持。
200
stream=true 时以 SSE 增量返回（text/event-stream）。
未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Message created
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Unique object identifier. The format and length of IDs may change over time. |
| container | null | object | Information about the container used in the request (for the code execution tool) |
| container.id | string | Identifier for the container used in this request |
| container.expires_at | string | The time at which the container will expire. |
| container.skills | null | array<object> | Skills loaded in the container |
| content | array<object> | Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{ "type": "text", "text": "Hi, I'm Claude." }] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Then the response `content` might be: ```json [{ "type": "text", "text": "B)" }] ``` |
| content[].citations | null | array<object> | Citations supporting the text block. The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. |
| content[].text | string | The text generated by the model. |
| content[].type | string | Always `text`. Discriminator that marks this object as a TextBlock in a `type`-tagged union. / Always `thinking`. Discriminator that marks this object as a ThinkingBlock in a `type`-tagged union. / Always `redacted_thinking`. Discriminator that marks this object as a RedactedThinkingBlock in a `type`-tagged union. / Always `tool_use`. Discriminator that marks this object as a ToolUseBlock in a `type`-tagged union. / Always `server_tool_use`. Discriminator that marks this object as a ServerToolUseBlock in a `type`-tagged union. / Always `web_search_tool_result`. Discriminator that marks this object as a WebSearchToolResultBlock in a `type`-tagged union. / Always `web_fetch_tool_result`. Discriminator that marks this object as a WebFetchToolResultBlock in a `type`-tagged union. / Always `code_execution_tool_result`. Discriminator that marks this object as a CodeExecutionToolResultBlock in a `type`-tagged union. / Always `bash_code_execution_tool_result`. Discriminator that marks this object as a BashCodeExecutionToolResultBlock in a `type`-tagged union. / Always `text_editor_code_execution_tool_result`. Discriminator that marks this object as a TextEditorCodeExecutionToolResultBlock in a `type`-tagged union. / Always `tool_search_tool_result`. Discriminator that marks this object as a ToolSearchToolResultBlock in a `type`-tagged union. / Always `container_upload`. Discriminator that marks this object as a ContainerUploadBlock in a `type`-tagged union. |
| content[].signature | string | A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See extended thinking for details. |
| content[].thinking | string | The text of Claude's thinking process for this block. |
| content[].data | string | The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See extended thinking for details. |
| content[].id | string | Id of the tool call; send it back as tool_use_id in the tool_result block that answers it. / Id of the server tool call; the matching result block repeats it as tool_use_id. |
| content[].caller | object | Which party invoked the tool: the model directly or a code execution tool. / Which party invoked the server tool: the model directly or a code execution tool. / Which party invoked the search: the model directly or a code execution tool. / Which party invoked the fetch: the model directly or a code execution tool. |
| content[].input | any | Arguments the model chose, as a JSON object that follows the tool's input_schema. / Arguments the model passed to the server tool, as a JSON object. |
| content[].name | string | Name of the tool the model wants to call. / Name of the server tool the model called, such as web_search, web_fetch or code_execution. |
| content[].toolset_name | null | string | For a toolset member tool_use, the toolset family. |
| content[].content | object | array<object> | object | object | object | object | object | Search results (array of web_search_result blocks) or an error object. / The fetched document or an error object. / Result of the code execution: a result block, an encrypted result block, or an error object. / Result of the bash command: a result block or an error object. / Result of the text editor command: a view, create or str_replace result block, or an error object. / Result of the tool search: a search result block that lists tool references, or an error object. |
| content[].tool_use_id | string | Id of the web_search server tool call this result belongs to. / Id of the web_fetch server tool call this result belongs to. / Id of the code_execution server tool call this result belongs to. / Id of the bash_code_execution server tool call this result belongs to. / Id of the text_editor_code_execution server tool call this result belongs to. / Id of the tool search server tool call this result belongs to. |
| content[].file_id | string | Id of the file that was uploaded into the code execution container. |
| model | string | The model that will complete your prompt. See models for additional details and options. |
| role | string | Conversational role of the generated message. This will always be `"assistant"`. |
| stop_details | null | object | Structured information about a refusal. |
| stop_details.category | null | string | The policy category that triggered a refusal. - `cyber` - The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `bio` - The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `frontier_llm` - The request could assist the development of competing AI models, which is restricted under Anthropic's commercial terms. Benign machine learning work can also trigger this category. - `reasoning_extraction` - The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use adaptive thinking. - `general_harms` - The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. |
| stop_details.explanation | null | string | Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. |
| stop_details.type | string | Always `refusal`. Discriminator that marks this object as a RefusalStopDetails in a `type`-tagged union. |
| stop_reason | null | string | The reason that we stopped. This may be one the following values: - `"end_turn"`: the model reached a natural stopping point - `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - `"tool_use"`: the model invoked one or more tools - `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - `"refusal"`: when streaming classifiers intervene to handle potential policy violations - `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. |
| stop_sequence | null | string | Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. |
| type | string | Object type. For Messages, this is always `"message"`. |
| usage | object | Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. |
| usage.cache_creation | null | object | Breakdown of cached tokens by TTL |
| usage.cache_creation_input_tokens | null | number | The number of input tokens used to create the cache entry. |
| usage.cache_read_input_tokens | null | number | The number of input tokens read from the cache. |
| usage.inference_geo | null | string | The geographic region where inference was performed for this request. |
| usage.input_tokens | number | The number of input tokens which were used. |
| usage.output_tokens | number | The number of output tokens which were used. |
| usage.output_tokens_details | null | object | Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. |
| usage.server_tool_use | null | object | The number of server tool requests. |
| usage.service_tier | null | string | If the request used the priority, standard, or batch tier. |
text/event-stream — chunk / 事件对象
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Optional id of the server-sent event. |
| event | string | Name of the server-sent event. |
| data | object | 完整 SDK RawMessageStreamEvent union |
| data.delta | object | Final fields of the message sent with message_delta: why generation stopped and the container. / The incremental change to the content block at index. |
| data.type | string | Always `message_delta`. Discriminator that marks this object as a RawMessageDeltaEvent in a `type`-tagged union. / Always `content_block_delta`. Discriminator that marks this object as a RawContentBlockDeltaEvent in a `type`-tagged union. / Always `message_start`. Discriminator that marks this object as a RawMessageStartEvent in a `type`-tagged union. / Always `message_stop`. Discriminator that marks this object as a RawMessageStopEvent in a `type`-tagged union. / Always `content_block_start`. Discriminator that marks this object as a RawContentBlockStartEvent in a `type`-tagged union. / Always `content_block_stop`. Discriminator that marks this object as a RawContentBlockStopEvent in a `type`-tagged union. |
| data.usage | object | Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. |
| data.index | number | Zero-based index of the content block this delta applies to. / Zero-based index of the content block that starts. / Zero-based index of the content block that ends. |
| data.message | object | The complete Message object being started; its content is empty at message_start and filled by the following content_block events. |
| data.content_block | object | The content block as it starts, with empty text or input to be filled by deltas. |
/model/v1/messages/count_tokens◐ 部分支持modelstring必填○ 当前不生效Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
接受但当前不生效。估算与模型无关，缺失或不存在的模型名仍可返回计数。
messagesarray必填◐ 部分支持Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.
仅按字符粗估，不能作为模型精确 token 数。
contentstring | array必填Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.
rolestring必填Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.
systemstring | array可选Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
计入估算。
toolsarray可选Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
计入估算。
tool_choiceobject可选○ 当前不生效Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
接受但当前不生效。不影响计数。
typestring必填Disable tool calls for this request.
disable_parallel_tool_useboolean可选Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.
namestring必填The name of the tool to use.
cache_controlobject可选○ 当前不生效Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
接受但当前不生效。不影响计数。
typestring必填Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.
ttlstring可选The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
output_configobject可选○ 当前不生效Body param: Configuration options for the model's output, such as the output format.
接受但当前不生效。不影响计数。
effortstring可选All possible effort levels.
formatobject可选A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
thinkingobject可选○ 当前不生效Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
接受但当前不生效。不影响计数。
budget_tokensnumber必填Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
typestring必填Let the model choose its reasoning budget, subject to output_config.effort when supplied.
displaystring可选Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
200
按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Token count
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| input_tokens | number | The total number of tokens across the provided list of messages, system prompt, and tools. |
/model/v1/models● 支持supported_apiarray可选query: Match any comma-separated declared protocol ID; omitted or empty includes all models. Combined with type and output_modalities using AND. Invalid IDs return 400 with all legal values.
typearray可选query: Filter by one or more model types (comma-separated).
按 type 筛选，多个值用逗号分隔；非法值返回 400 并列出合法值。
output_modalitiesarray可选query: Match any comma-separated output modality; all disables modality filtering. Combined with type using AND.
匹配任一逗号分隔的输出模态；all 不限制模态，与 type 条件同时生效。
limitstring可选○ 当前不生效query: Accepted for compatibility and ignored: this endpoint always returns the full model catalog. Filter with type and output_modalities instead.
接受但当前不生效；此端点返回完整模型目录。
qstring可选○ 当前不生效query: Accepted for compatibility and ignored: this endpoint always returns the full model catalog. Filter with type and output_modalities, or match ids on the client.
接受但当前不生效；此端点返回完整模型目录。
200 list
OCR 模型的 type 为 ocr，pricing.page 是 USD/页的十进制字符串，为 Praxis 对 Vercel 模型列表形状的扩展；其余四项 token 价格为 0。其它模型不带 pricing.page。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Model list
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `list`. |
| data | array<object> | Published models, in the order the catalog returns them, filtered by type, supported_api and output_modalities when given. |
| data[].id | string | Model id to pass as `model` in other calls. It can carry a creator prefix such as deepseek/deepseek-v4-pro. |
| data[].object | string | Object type; always `model`. |
| data[].created | number | Unix time in seconds at which the model was first published. |
| data[].owned_by | string | Organization that serves the model on this platform; always `deepractice`. |
| data[].name | string | Display name, prefixed with the vendor when one is known, for example `Vendor: Model`. |
| data[].description | string | null | Free-text description of the model; null when none is published. |
| data[].context_window | number | null | Maximum context length in tokens (input plus output); null when the catalog has no figure. |
| data[].max_tokens | number | null | Maximum number of output tokens the model can produce in one call; null when the catalog has no figure. |
| data[].type | string | Kind of model; it decides which endpoint accepts it. |
| data[].supported_apis | array<string> | Declared protocol IDs in stable lexicographic order; an empty array means no protocol is declared. Use these IDs with supported_api to find models for an operation. |
| data[].tags | array<string> | Capability tags of the model such as `tools`, `vision` or `reasoning`; use them to filter for features. |
| data[].architecture | object | Native modalities of the model. |
| data[].x_praxis | object | Platform extension. input_modalities states, per input format, how the model takes it. |
| data[].pricing | object | Prices in USD per named unit, as decimal strings. A unit that is absent is unpriced, which is not the same as free. |
| data[].released | string | Date (YYYY-MM-DD, UTC) on which the model was first published. |
/model/v1/models/{model}● 支持modelstring必填path: Id of the model to read. It may carry a creator prefix with a slash, such as deepseek/deepseek-v4-pro, so the value runs to the end of the path. Ids come from the `id` field of listModels; an unknown id answers 404.
200 model
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Model
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Model id to pass as `model` in other calls. It can carry a creator prefix such as deepseek/deepseek-v4-pro. |
| object | string | Object type; always `model`. |
| created | number | Unix time in seconds at which the model was first published. |
| owned_by | string | Organization that serves the model on this platform; always `deepractice`. |
| name | string | Display name, prefixed with the vendor when one is known, for example `Vendor: Model`. |
| description | string | null | Free-text description of the model; null when none is published. |
| context_window | number | null | Maximum context length in tokens (input plus output); null when the catalog has no figure. |
| max_tokens | number | null | Maximum number of output tokens the model can produce in one call; null when the catalog has no figure. |
| type | string | Kind of model; it decides which endpoint accepts it. |
| supported_apis | array<string> | Declared protocol IDs in stable lexicographic order; an empty array means no protocol is declared. Use these IDs with supported_api to find models for an operation. |
| tags | array<string> | Capability tags of the model such as `tools`, `vision` or `reasoning`; use them to filter for features. |
| architecture | object | Native modalities of the model. |
| architecture.modality | string | Native modalities as `input+input->output+output`, for example `text+image->text`. |
| architecture.input_modalities | array<string> | Input modalities the model accepts natively, for example text, image, file or audio. |
| architecture.output_modalities | array<string> | Output modalities the model produces, for example text, image, audio, video, embeddings or rerank. |
| architecture.tokenizer | string | null | Tokenizer family; null because the platform does not publish it. |
| architecture.instruct_type | string | null | Instruction template type; null because the platform does not publish it. |
| x_praxis | object | Platform extension. input_modalities states, per input format, how the model takes it. |
| x_praxis.input_modalities | object | Per input format, whether the model takes it natively, through a conversion step, or not at all. Conversion depends on the file-parser plugin settings. |
| pricing | object | Prices in USD per named unit, as decimal strings. A unit that is absent is unpriced, which is not the same as free. |
| pricing.input | string | USD per input token. |
| pricing.output | string | USD per output token. |
| pricing.input_cache_read | string | USD per input token that is read from the prompt cache. |
| pricing.input_cache_write | string | USD per input token that is written to the prompt cache. |
| pricing.image | string | USD per image; present only for a flat registry price. |
| pricing.video_second | string | Praxis extension: USD per second of output video. |
| pricing.audio_input_minute | string | Praxis extension: USD per minute of input audio. |
| pricing.audio_output_minute | string | Praxis extension: USD per minute of output audio. |
| pricing.input_character | string | Praxis extension: USD per input character. |
| pricing.page | string | Praxis extension: USD per page, present only for OCR models; not a Vercel AI Gateway pricing field. |
| released | string | Date (YYYY-MM-DD, UTC) on which the model was first published. |
先调用「对话」，从响应头 X-Praxis-Generation-Id 取得 id，替换 gen_123。
/model/v1/generation● 支持idstring必填◐ 部分支持query: Generation ID from the X-Praxis-Generation-Id response header of the model request.
使用 /model 响应头 X-Praxis-Generation-Id；响应体 id 和 X-Request-Id 不能查询，返回 404。
200
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Generation record
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Generation id that was queried. |
| model | string | Model that served the generation. |
| cost | number | null | Cost charged for the generation in USD; null when not yet priced. |
| usage | object | Token usage of the generation. |
| usage.prompt_tokens | number | Number of prompt tokens. |
| usage.completion_tokens | number | Number of tokens in the completion. |
| usage.total_tokens | number | Prompt plus completion tokens. |
| usage.cached_input_tokens | number | Prompt tokens served from the prompt cache; null when not reported. |
| latency_ms | number | null | Latency of the generation in milliseconds; null when not recorded. |
| created | number | Unix time in seconds at which the generation was recorded. |
/model/v1/conversations● 支持itemsarray可选Initial items, at most 20 per request. Router support (supported): Verified to take effect.
已验证生效。
metadataobject可选Up to 16 string key/value pairs stored with the conversation; keys at most 64 characters and values at most 512. Router support (supported): Verified to take effect.
已验证生效。
200 conversation
创建一个会话，可选携带初始 items（一次最多 20 条）与 metadata。会话按租户分区，创建者是唯一能引用它的租户。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The created conversation
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。
/model/v1/conversations/{conversation_id}● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
200 conversation
按 ID 读取一个会话。不存在或属于其他租户都返回 404 conversation_not_found。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The conversation
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。
/model/v1/conversations/{conversation_id}● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
metadataobject必填Replacement metadata. The whole object replaces the old one; it is not merged. Up to 16 pairs, keys at most 64 characters and values at most 512. Router support (supported): Verified to take effect.
已验证生效。
200 conversation
更新一个会话的 metadata——整体替换，不与已有 metadata 合并。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The updated conversation
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。
/model/v1/conversations/{conversation_id}/items● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
itemsarray必填Items to append, between 1 and 20 per request. Router support (supported): Verified to take effect.
已验证生效。
200 list
向一个会话追加 items（一次最多 20 条），返回刚追加的这些 items。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The items just added
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `list`. |
| data | array<object> | Items of the conversation, in the order the list requested. |
| first_id | string | Id of the first item of this page; null for an empty page. |
| last_id | string | Id of the last item of this page; null for an empty page. |
| has_more | boolean | Whether more items exist beyond this page; pass `last_id` as `after` to read them. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。
/model/v1/conversations/{conversation_id}/items● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
limitinteger可选query: Maximum items per page (values above 100 are clamped).
afterstring可选query: Item ID from the previous page; returns items after this cursor.
orderstring可选query: Sort by stored creation order.
200 list
按创建顺序列出会话的 items，支持 limit/after/order 分页参数。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The conversation's items
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `list`. |
| data | array<object> | Items of the conversation, in the order the list requested. |
| first_id | string | Id of the first item of this page; null for an empty page. |
| last_id | string | Id of the last item of this page; null for an empty page. |
| has_more | boolean | Whether more items exist beyond this page; pass `last_id` as `after` to read them. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。 条目 ID 取自「添加对话条目」或「列出对话条目」，替换 item_123。
/model/v1/conversations/{conversation_id}/items/{item_id}● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
item_idstring必填path: Id of the item to read, from the `id` of an item returned by createConversationItems or listConversationItems. An id that is not in the conversation answers 404.
200
按 ID 读取会话里的单条 item。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The item
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| $ | object |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。 条目 ID 取自「添加对话条目」或「列出对话条目」，替换 item_123。
/model/v1/conversations/{conversation_id}/items/{item_id}● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
item_idstring必填path: Id of the item to delete, from the `id` of an item returned by createConversationItems or listConversationItems. An id that is not in the conversation answers 404.
200 conversation
删除会话里的单条 item，返回该会话对象（不是被删除的 item）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
The conversation, with the item removed
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
先调用「创建对话」拿到 conv_ 开头的 ID，替换 conv_123。
/model/v1/conversations/{conversation_id}● 支持conversation_idstring必填path: Id of the conversation, the `id` of the object returned by createConversation (it looks like conv_...). Another tenant's conversation, an unknown id and a deleted conversation all answer 404 conversation_not_found.
200 conversation.deleted
删除一个会话。删除后该会话与其 items 都不能再被引用（包括作为 Responses create 的 conversation 参数）。
鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见 错误码
Deletion confirmation
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | Id of the deleted conversation. |
| object | string | Object type; always `conversation.deleted`. |
| deleted | boolean | Always true; neither the conversation nor its items can be referenced again. |