请求参数

• X-OpenRouter-Metadatastring可选○ 当前不生效

  header: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility.

  接受但当前不生效；不会返回请求的路由元数据。

  取值 disabledenabled
• messagesarray必填◐ 部分支持

  List of messages for the conversation

  文本、角色、历史和工具往返生效；图片受模型尺寸限制；file_id 可引用 user_data 图片、文本和 PDF；模型读取能力与失败处理见[文件引用指南](/docs/cloud/services/model/guides/files)。

  ▸ 展开子字段（12）

  元素按 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.

    取值 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

• modelstring可选

  Model to use for completion

  主模型；提供非空 models 时可省略，使用列表首项。

• streamboolean可选◐ 部分支持
  默认 false

  Enable streaming response

  流式正文和工具增量生效；gemini-2.5-flash 可能缺少结束标记，预算耗尽时 finish_reason 可能不准确。

• temperaturenumber可选◐ 部分支持

  Sampling temperature (0-2)

  在 /openai 的 deepseek-v4-flash 观察到效果；其余模型的采样差异无法确认。

• 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 同传时本字段优先。

• top_pnumber可选◐ 部分支持

  Nucleus sampling parameter (0-1)

  仅 /model 的 glm-5.3-flash 观察到效果；其余已测模型或协议面接受但未见效果。

• stopstring | array可选◐ 部分支持

  Stop sequences (up to 4)

  qwen3.8-flash 生效；deepseek-v4-flash、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 的具名函数结果不稳定。

  ▸ 展开子字段（2）

  • functionobject必填

    The function the model must call.

  • typestring必填

    OpenRouter server-tool type to force (e.g. `openrouter:web_search`, `web_search`, `web_search_preview`).

• ▸ 更多参数（48）

  • response_formatobject可选◐ 部分支持

    Response format configuration

    json_object 生效；json_schema 在 deepseek-v4-flash、qwen3.8-flash 生效，glm-5.3-flash 接受但未遵守。

    ▸ 展开子字段（3）

    按 type 区分（grammar / json_object / json_schema / python / text），此处展开其中一种的形状

    • typestring必填

      Always `python`. Discriminator that marks this object as a ChatFormatPythonConfig in a `type`-tagged union.

      取值 python
    • json_schemaobject必填

      JSON Schema configuration object

    • grammarstring必填

      Custom grammar for text generation

  • 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.

    ▸ 展开子字段（2）

    • ttlstring可选

      Lifetime of an Anthropic-style cache breakpoint.

      取值 5m1h
    • typestring必填

      Always `ephemeral`. Discriminator that marks this object as a AnthropicCacheControlDirective in a `type`-tagged union.

      取值 ephemeral
  • debugobject可选

    Debug options for inspecting request transformations (streaming only)

    ▸ 展开子字段（1）

    • 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 并点名字段。

    ▸ 展开子字段（27）

    元素按 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.

      取值 lowmediumhighxhighmax
    • 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.

      取值 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".

      取值 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.

      取值 instantfastautodeep-litedeepdeep-reasoningturbobasicadvanced
    • 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".

      取值 promptweighted_avg
    • 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.

      取值 general-highgeneral-budgetgeneral-fast
    • 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.

    ▸ 展开子字段（2）

    • 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.

      取值 content
  • presence_penaltynumber可选◐ 部分支持

    Presence penalty (-2.0 to 2.0)

    deepseek-v4-flash 的 /openai 面观察到效果；qwen3.8-flash 部分请求返回 400，其余不可观测。

  • prompt_cache_keystring可选
  • 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.

    ▸ 展开子字段（2）

    • modestring必填

      Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint.

      取值 explicit
    • 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 生效，其余选项接受但不生效。

    ▸ 展开子字段（13）

    • 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.

      接受但当前不生效（不属于供应商选择，平台凭证下可用）。

      取值 denyallownull
    • 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

    ▸ 展开子字段（2）

    • effortstring可选◐ 部分支持

      Constrains effort on reasoning for reasoning models

      none 仅在 qwen3.8-flash 可靠关闭思考；deepseek-v4-flash 和 glm-5.3-flash 未遵守。

      取值 maxxhighhighmediumlowminimalnonenull
    • summarystring可选○ 当前不生效

      How detailed the reasoning summary should be.

      接受但当前不生效。deepseek-v4-flash 未返回请求的摘要。

      取值 autoconcisedetailednull
  • 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 的档位效果不符合预期。

    取值 maxxhighhighmediumlowminimalnonenull
  • 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").

    取值 fallbacksortnull
  • 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`.

    取值 autodefaultfastflexpriorityscalenull
  • 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.

  • 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.

    ▸ 展开子字段（6）

    元素按 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.

      取值 finish_reason_is
    • 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

    ▸ 展开子字段（1）

    • 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.

    ▸ 展开子字段（5）

    • 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 延迟工具协议。

  • promptstring可选○ 当前不生效

    接受并忽略；Chat 仍须提供 messages，本字段不替代消息。

  • structured_outputsboolean可选○ 当前不生效

    接受并忽略此开关；结构化输出使用 response_format，支持度见该字段。

  • include_reasoningboolean可选○ 当前不生效

    接受并忽略此旧别名；思考配置使用 reasoning，支持度见该字段。

  • safe_promptboolean可选○ 当前不生效

    接受并忽略；未实现 Mistral 的 safe_prompt 开关。

  • raw_modeboolean可选○ 当前不生效

    接受并忽略；未实现 Hyperbolic 的 raw_mode 开关。

返回

200 chat.completion

stream=true 时以 SSE 增量返回（text/event-stream）。

未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。

错误按 OpenAI 格式返回，参见 错误码

请求体

• modelstring必填◐ 部分支持

  已验证支持 glm-5.3-flash、deepseek-flash；没有 Responses 协议的模型返回 404。

• streamboolean可选◐ 部分支持
  默认 false

  deepseek-flash 生效；glm-5.3-flash 返回 400。

• temperaturenumber可选◐ 部分支持

  glm-5.3-flash 部分生效，2 可能返回空文本或乱码；deepseek-flash 的效果不可观测。

• top_pnumber可选◐ 部分支持

  glm-5.3-flash 观察到采样变化；deepseek-flash 不可观测。

• toolsarray可选◐ 部分支持

  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。

  ▸ 展开子字段（4）

  • namestring必填

    Name of the function or tool the model must call.

  • typestring必填

    Kind of tool the model must call.

    取值 shell
  • 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}.

• backgroundboolean可选◐ 部分支持

  是否让模型在后台生成响应。仅当路由到的模型具备 Router 自建后台能力时可用——Router 会立即返回 status queued，随后自行以流式方式调用上游、跑到终态并恰好一次结算用量， 客户端通过 GET /v1/responses/{id} 轮询（这不代表上游原生支持 OpenAI 的 background 参数）。不具备该能力的 provider 设置为 true 仍返回 400（错误码 native_responses_background_unsupported）。取消（POST /v1/responses/{id}/cancel） 只能停止我方对上游流的继续读取，不能保证已发往上游的算力停止计算；用量按实际收到的 部分结算，未收到用量时按平台通用的"上游未报用量"规则处理。

  deepseek-flash 生效；glm-5.3-flash 返回 400。background 与 stream 同传时返回 JSON。

• includearray可选◐ 部分支持

  原样转发给上游模型；只对该模型具备的能力生效（例如推理内容、联网搜索来源），模型不具备的项会被忽略。

  deepseek-flash 返回 logprobs；reasoning.encrypted_content 仅为占位串。glm-5.3-flash 接受但当前不生效。

• 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。

• instructionsstring可选

  已验证生效。

• ▸ 更多参数（21）

  • max_output_tokensinteger可选

    正数控制输出预算；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可选◐ 部分支持

    true 可返回多个调用；false 接受但当前不生效，仍可能返回多个调用。

  • previous_response_idany可选

    要续接的上一条响应 ID。仅所有者可续接，续接时可以省略 model 字段；平台会展开保存的历史后再请求上游。

    平台将祖先的输入与输出和本轮 input 合并，发往上游前移除 previous_response_id；没有活副本或不属于当前租户时返回 404 previous_response_not_found。

  • promptobject可选○ 未支持

    引用一个已保存的提示词模板及其变量。我方目前没有 Prompts（提示词模板）资源，传入任何 id 都会返回 404 object_not_found。

    当前没有可引用的提示词模板；传入模板 id 返回 404。

    ▸ 展开子字段（2）

    • 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.

  • prompt_cache_keystring可选
  • 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.

    ▸ 展开子字段（2）

    • modestring必填

      Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint.

      取值 explicit
    • ttlstring可选

      Lifetime of cache entries, for example 30m; null leaves the provider default.

  • reasoningobject可选

    Configuration for reasoning mode in the response

    ▸ 展开子字段（6）

    • 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.

      取值 autoall_turnscurrent_turnnull
    • effortstring可选◐ 部分支持

      How much reasoning the model should spend.

      deepseek-flash 的 none 可关闭思考，其余档位不保证单调；glm-5.3-flash 接受但当前不生效，none 仍思考。

      取值 maxxhighhighmediumlowminimalnonenull
    • 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.

      取值 standardpronull
    • summarystring可选◐ 部分支持

      How detailed the reasoning summary should be.

      glm-5.3-flash 的 concise 偶发有摘要，auto/detailed 未见；deepseek-flash 接受但当前不生效。

      取值 autoconcisedetailednull
    • enabledboolean可选
    • max_tokensinteger可选
  • safety_identifierstring可选

    建议为终端用户设置的稳定标识符，用于滥用隔离。使用稳定的 ID、哈希值或化名。若上游 provider 需要用户身份，我们会把它折算进转发的哈希身份、不会原样转发；省略时请求使用账号级身份，滥用处置可能影响整个账号。

  • service_tierstring可选
    默认 "auto"

    请求使用的服务档位；当前效果不可观测。

    取值 autodefaultfastflexpriorityscalenull
  • storeboolean可选
    默认 true

    是否在服务端保存这条响应，以便之后通过 previous_response_id 读取或续接。默认 true；传 false 可关闭保存。

    true 保存响应供读取；false 不保存，读取返回 404。

  • textobject可选

    Text output configuration including format and verbosity

    ▸ 展开子字段（2）

    • formatobject可选◐ 部分支持

      Text response format configuration

      json_object、json_schema 生效（预算需足够）；text 在 glm-5.3-flash 偶发 400，在 deepseek-flash 生效。

    • verbositystring可选○ 当前不生效

      接受但当前不生效。glm-5.3-flash、deepseek-flash 均未观察到长度变化。

      取值 lowmediumhighxhighmaxnull
  • top_logprobsinteger可选◐ 部分支持

    deepseek-flash 生效，允许 0–20；glm-5.3-flash 返回空 logprobs。

  • truncationstring可选

    How to handle input that exceeds the context window.

    取值 autodisablednull
  • 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可选

    该响应所属的对话（会话 id 字符串，或 `{id}` 对象）。发往上游前，我们会把这个对话里已有的条目拼接到本次 input 前面；响应完成后，本次的输入与输出条目会被追加回这个对话。只有对话的所有者可以引用它，否则返回 404 object_not_found；不能和 previous_response_id 同时使用，同传返回 400。

    会话历史进入本次输入，响应条目追加到会话；不能与 previous_response_id 同传。

  • context_managementarray可选

    本次请求的上下文管理配置（例如输入超过阈值时自动压缩）。

  • moderationobject可选

    对本次响应的输入和输出运行审核（moderation）的配置。

  • prompt_cache_retentionstring可选

    提示词缓存的保留策略；设为 24h 可以让缓存前缀存活更久，最长 24 小时。

  • stream_optionsobject可选

    流式响应的附加选项，只在 stream=true 时生效（例如流末尾是否附带用量统计）。

  • access_programsobject可选○ 未支持

    已识别的官方字段；平台未实现访问计划，传入返回 400 并明确说明不支持。

返回

200 response

stream=true 时以 SSE 增量返回（text/event-stream）。

未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• response_idstring必填

  path:

返回

200 response

按 ID 读取一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，读取会返回 404 response_not_found；超过保留期（默认 30 天）后读取也会返回同样的 404。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• response_idstring必填

  path:

返回

200 response

按 ID 立即删除一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，删除会返回 404 response_not_found。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• response_idstring必填

  path:

返回

200 response

仅对以 background:true 创建、且路由到具备后台生成能力的模型的响应可用：取消是 幂等的，重复调用返回同一个终态响应；我方的取消只能停止我方对上游流的继续读取， 不能保证已发往上游的算力停止计算，用量按实际收到的部分结算。对一个非后台 （同步）响应调用 cancel：如果这个响应 id 不存在（未持久化、已过期或 id 有误）， 返回 404 object_not_found；如果响应存在但其来源 provider 没有声明支持 cancel 操作（我们目前没有接入任何为同步响应声明该能力的上游），返回 400 native_responses_operation_unsupported。这两种情况都不是尚未实现的 501 gate。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• response_idstring必填

  path:

返回

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。

错误按 OpenAI 格式返回，参见 错误码

请求体

• itemsarray可选

  已验证生效。

• metadataobject可选

  已验证生效。

返回

200 conversation

创建一个会话，可选携带初始 items（一次最多 20 条）与 metadata。会话按租户分区，创建者是唯一能引用它的租户。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

返回

200 conversation

按 ID 读取一个会话。不存在或属于其他租户都返回 404 conversation_not_found。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

• metadataobject必填

  已验证生效。

返回

200 conversation

更新一个会话的 metadata——整体替换，不与已有 metadata 合并。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

返回

200 conversation.deleted

删除一个会话。删除后该会话与其 items 都不能再被引用（包括作为 Responses create 的 conversation 参数）。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

• itemsarray必填

  已验证生效。

返回

200 list

向一个会话追加 items（一次最多 20 条），返回刚追加的这些 items。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

• limitinteger可选
  默认 20

  query: Maximum items per page (values above 100 are clamped).

• afterstring可选

  query: Item ID from the previous page; returns items after this cursor.

• orderstring可选
  默认 "desc"

  query: Sort by stored creation order.

  取值 ascdesc

返回

200 list

按创建顺序列出会话的 items，支持 limit/after/order 分页参数。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

• item_idstring必填

  path:

返回

200

按 ID 读取会话里的单条 item。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• conversation_idstring必填

  path:

• item_idstring必填

  path:

返回

200 conversation

删除会话里的单条 item，返回该会话对象（不是被删除的 item）。

错误按 OpenAI 格式返回，参见 错误码

请求体

• modelstring必填

  已验证生效。

• response_formatstring可选○ 未支持

  Omit for GPT Image models, which return native base64 data. Only send for models that explicitly support response_format; platform hosting is a separate Image extension.

  gpt-image-2 传 b64_json 或 url 均返回 400；请省略此字段。

  取值 urlb64_json
• promptstring必填

  已验证生效。

• ninteger可选
  默认 1

  控制图片数量，0 返回 400，允许 1–10。

• sizestring可选◐ 部分支持

  gpt-image-2 已验证 1024x1024、1024x1536；512x512 返回 400。

  取值 1024x10241024x15361536x1024auto
• qualitystring可选

  已验证生效。

  取值 lowmediumhighauto
• backgroundstring可选

  gpt-image-2 的 transparent 返回透明 PNG。

• output_formatstring可选

  gpt-image-2 的 jpeg 返回 JPEG。

返回

200

错误按 OpenAI 格式返回，参见 错误码

请求参数

• offsetinteger可选
  默认 0

  query: Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned

  已验证生效。

• limitinteger可选

  query: Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned

  已验证生效。

• categorystring可选○ 当前不生效

  query: Filter models by use case category

  接受但当前不生效。当前不会按此条件过滤或排序模型。

  取值 programmingroleplaymarketingmarketing/seotechnologysciencetranslationlegalfinancehealthtriviaacademia
• supported_parametersstring可选○ 当前不生效

  query: Filter models by supported parameter (comma-separated)

  接受但当前不生效。当前不会按此条件过滤或排序模型。

• output_modalitiesstring可选

  query: Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or "all" to include all models. When omitted, all models are included; comma-separated modalities match any output.

  已验证生效。

• sortstring可选

  query: Sort by newest creation date or lowest declared USD unit rate (not estimated request cost). Unpriced models sort last; ties retain catalog order.

  已验证生效。

  取值 newestprice_low
• qstring可选

  query: Free-text search by model name or slug.

  已验证生效。

• input_modalitiesstring可选○ 当前不生效

  query: Filter models by input modality. Comma-separated list of: text, image, audio, file.

  接受但当前不生效。当前不会按此条件过滤或排序模型。

• contextinteger可选○ 当前不生效

  query: Minimum context length (tokens). Models with smaller context are excluded.

  接受但当前不生效。当前不会按此条件过滤或排序模型。

• min_pricenumber可选○ 当前不生效

  query: Minimum prompt price in $/M tokens.

  接受但当前不生效。当前不会按此条件过滤或排序模型。

• ▸ 更多参数（20）

  • max_pricenumber可选○ 当前不生效

    query: Maximum prompt price in $/M tokens.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • archstring可选○ 当前不生效

    query: Filter models by architecture/model family (e.g. GPT, Claude, Gemini, Llama).

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • model_authorsstring可选○ 当前不生效

    query: Filter models by the organization that created the model. Comma-separated list of author slugs.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • providersstring可选○ 当前不生效

    query: Filter models by hosting provider. Comma-separated list of provider names.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • distillablestring可选○ 当前不生效

    query: Filter by distillation capability. "true" returns only distillable models, "false" excludes them.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

    取值 truefalse
  • zdrstring可选○ 当前不生效

    query: When set to "true", return only models with zero data retention endpoints.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

    取值 true
  • regionstring可选○ 当前不生效

    query: Filter to models with endpoints in the given data region ("eu" or "us").

    接受但当前不生效。当前不会按此条件过滤或排序模型。

    取值 euus
  • min_output_pricenumber可选○ 当前不生效

    query: Minimum completion (output) price in $/M tokens.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_output_pricenumber可选○ 当前不生效

    query: Maximum completion (output) price in $/M tokens.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • min_age_daysinteger可选○ 当前不生效

    query: Minimum model age in days since its creation date.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_age_daysinteger可选○ 当前不生效

    query: Maximum model age in days since its creation date.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • min_intelligence_indexnumber可选○ 当前不生效

    query: Minimum Artificial Analysis intelligence index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_intelligence_indexnumber可选○ 当前不生效

    query: Maximum Artificial Analysis intelligence index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • min_coding_indexnumber可选○ 当前不生效

    query: Minimum Artificial Analysis coding index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_coding_indexnumber可选○ 当前不生效

    query: Maximum Artificial Analysis coding index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • min_agentic_indexnumber可选○ 当前不生效

    query: Minimum Artificial Analysis agentic index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_agentic_indexnumber可选○ 当前不生效

    query: Maximum Artificial Analysis agentic index.

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • min_tool_success_ratenumber可选○ 当前不生效

    query: Minimum tool-calling success rate, as a fraction in [0, 1] (e.g. 0.9 = 90% of requests finishing with a tool_calls finish reason).

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • max_tool_success_ratenumber可选○ 当前不生效

    query: Maximum tool-calling success rate, as a fraction in [0, 1].

    接受但当前不生效。当前不会按此条件过滤或排序模型。

  • apiarray可选

    query: Match any comma-separated API family: chat selects openai.chat.completions; responses selects openai.responses; embeddings selects openai.embeddings; images selects openai.images.*; audio selects openai.audio.*; videos selects openai.videos. Omitted or empty includes all OpenAI-offered models. Other filters combine using AND, before pagination. Invalid values return 400 with all legal values.

    按声明的 OpenAI 协议筛选，逗号分隔匹配任一协议族，在分页前生效。

返回

200 list

错误按 OpenAI 格式返回，参见 错误码

请求参数

• modelstring必填

  path: Model ID from GET /openai/v1/models, including any publisher prefix.

返回

200 model

返回与列表中同一条目相同的模型对象。只有声明了 OpenAI 协议的模型可见；模型 ID 可以带斜杠分隔的发布方前缀。不存在或没有声明 OpenAI 协议的模型返回 404。

错误按 OpenAI 格式返回，参见 错误码

请求体

• modelstring必填

  The model to use for embeddings

  已验证生效。

• 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 为向量的二进制编码。

  取值 floatbase64
• inputstring | array必填◐ 部分支持

  Text, token, or multimodal input(s) to embed

  文本及文本数组生效；token 整数数组返回 400。图片仅 qwen3-vl-embedding、doubao-embedding-vision 支持；text-embedding-3-small 的 16 条批量返回 400。

• 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可选◐ 部分支持

  Provider routing preferences for the request.

  bge-m3、qwen3-embedding-0.6b 返回 400；text-embedding-3-small 接受，但效果不可观测。

  ▸ 展开子字段（13）

  • 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.

    取值 denyallownull
  • 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 接受，但效果不可观测。

  ▸ 展开子字段（5）

  • 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

转发方式与对话（chat completions）一致，用量算在同一份计费里。 未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。

错误按 OpenAI 格式返回，参见 错误码

请求体

• 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).

  ▸ 展开子字段（1）

  • 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`.

  ▸ 展开子字段（1）

  • 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.

  ▸ 展开子字段（3）

  • 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.

    取值 first_framelast_frame
  • 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`.

• ▸ 更多参数（4）

  • 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 video

异步生成视频：创建任务后轮询状态，完成后下载内容。按输出秒数计费，每秒价格见 GET /model/v1/models 的 pricing.video_second（USD/秒）。请显式选择已注册的视频模型，例如 wan2.7-t2v。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• 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可选
  默认 20

  query: Maximum number of jobs per page, from 1 to 100; defaults to 20.

  分页参数生效；limit 为 1–100，order 为 asc/desc，after 必须引用存在的任务。

• orderany可选
  默认 "desc"

  query: Sort order by creation time: desc (default) lists the newest job first, asc the oldest first.

  分页参数生效；limit 为 1–100，order 为 asc/desc，after 必须引用存在的任务。

  取值 ascdesc

返回

200 list

列出本账号的视频任务。limit 为 1 到 100，order 为 asc 或 desc，after 必须引用存在的任务。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• 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 video

读取任务的当前状态和进度。status 为 queued 或 in_progress 时继续轮询，failed 时查看 error，completed 后才能下载内容。任务不存在返回 404。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• 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可选◐ 部分支持
  默认 "video"

  query: Spritesheet is not available in this release (400).

  video、thumbnail 生效；spritesheet 返回 400。

  取值 videothumbnailspritesheet
• indexinteger可选◐ 部分支持

  query: Output index; this release produces index 0. variant takes precedence.

  视频仅支持 index=0；大于 0 或负数返回 400。variant=thumbnail 时 index 接受但当前不生效。

返回

200

任务 completed 后下载视频文件（video，MP4）或缩略图（thumbnail）；spritesheet 返回 400，index 只支持 0。任务不存在返回 404。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• 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 video.deleted

删除任务及其生成的内容。任务不存在返回 404。

错误按 OpenAI 格式返回，参见 错误码

请求体

• modelstring必填

  已验证生效。

• temperaturenumber可选○ 未支持

  whisper-large-v3-turbo、qwen3-asr-flash 均返回 400。

• response_formatstring可选◐ 部分支持
  默认 "json"

  json/text 均生效；verbose_json 仅 whisper-large-v3-turbo 支持。srt/vtt 均返回 400。

  取值 jsontextverbose_json
• filestring必填

  已验证生效。

• languagestring可选◐ 部分支持

  两模型接受 ISO 语言码；qwen3-asr-flash 可能按指定语言翻译输出，whisper-large-v3-turbo 用作输入语言提示。非 ISO 名称可能报 502。

• promptstring可选◐ 部分支持

  仅 whisper-large-v3-turbo 的词表提示已验证生效；qwen3-asr-flash 返回 400。

• timestamp_granularities[]array可选◐ 部分支持

  仅 whisper-large-v3-turbo 在 verbose_json 下支持 segment；word 返回 400；qwen3-asr-flash 不支持时间戳。

返回

200

标准请求字段；不能表达的参数返回 input_not_representable。

错误按 OpenAI 格式返回，参见 错误码

请求体

• filestring必填

  The File object (not file name) to be uploaded.

  已验证生效。

• purposestring必填◐ 部分支持

  文件用途：user_data、assistants 或 vision（vision 只接受 PNG、JPEG、GIF、WebP 图片）。OpenAI 的 batch、fine-tune、evals 等其余用途不支持，返回 400 PURPOSE_UNSUPPORTED。

  支持 user_data、assistants、vision；batch、fine-tune、evals 等其余值返回 400。

  取值 user_dataassistantsvision
• expires_afterobject可选

  The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.

  anchor=created_at，seconds=3600–2592000。

  ▸ 展开子字段（2）

  • anchorstring必填

    Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.

    取值 created_at
  • secondsinteger必填

    The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

返回

200 file

单文件最多 100 MB（104857600 字节）；按内容识别 PDF、Office、图片、音频、视频与 UTF-8 文本。purpose 支持 user_data / assistants / vision；其他用途、空文件、不支持类型和超限均返回 400。不支持 Uploads 分片。只接受表单 file、purpose、expires_after[anchor]、expires_after[seconds]；其他表单字段或任何查询参数返回 400 invalid_request_error，消息为 "Unrecognized request argument supplied: <字段>"，param 为该字段。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• purposestring可选

  query: Only return files with the given purpose.

  已验证生效。

• limitinteger可选
  默认 10000

  query: A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

  已验证生效。

• orderstring可选
  默认 "desc"

  query: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

  已验证生效。

  取值 ascdesc
• afterstring可选

  query: A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

  已验证生效。

返回

200 list

只接受查询参数 after、order、limit、purpose；其他查询参数返回 400 invalid_request_error，消息为 "Unrecognized request argument supplied: <参数>"，param 为该参数。

错误按 OpenAI 格式返回，参见 错误码

请求参数

• file_idstring必填

  path: The ID of the file to use for this request.

返回

200 file

错误按 OpenAI 格式返回，参见 错误码

请求参数

• file_idstring必填

  path: The ID of the file to use for this request.

返回

200 file

错误按 OpenAI 格式返回，参见 错误码

请求参数

• file_idstring必填

  path: The ID of the file to use for this request.

返回

200

错误按 OpenAI 格式返回，参见 错误码