Request parameters

• X-OpenRouter-Metadatastring可选○ Currently ignored

  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.

  Accepted but currently has no effect; the requested routing metadata is not returned.

• modelstring必填

  Model to use for completion

  Primary model; optional when a nonempty models list supplies the first candidate.

• messagesarray必填◐ Partially supported

  List of messages for the conversation

  Text, roles, history and tool round trips work. Images have model-specific size limits. file_id accepts user_data images, text and PDF; see the [file reference guide](/en/docs/cloud/services/model/guides/files) for model support and failure handling.

  ▸ 展开子字段（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

• max_tokensinteger可选◐ Partially supported

  Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16.

  Works on deepseek-v4-flash and glm-5.3-flash; small budgets may not take effect on qwen3.8-flash. Takes precedence over max_completion_tokens.

• streamboolean可选◐ Partially supported
  默认 false

  Enable streaming response

  Content and tool deltas stream; gemini-2.5-flash may omit the end sentinel and budget exhaustion may report an incorrect finish_reason.

• temperaturenumber可选◐ Partially supported

  Sampling temperature (0-2)

  An effect was observed on deepseek-v4-flash via /openai; sampling effects on other models remain unobservable.

• top_pnumber可选◐ Partially supported

  Nucleus sampling parameter (0-1)

  An effect was observed only on glm-5.3-flash via /model; other tested models or faces accepted it without an observed effect.

• toolsarray可选

  Available tools for function calling

  Verified to take effect.

• tool_choicestring | object可选◐ Partially supported

  Tool choice configuration

  auto works. deepseek-v4-flash ignores none/required/named functions; qwen3.8-flash rejects required/named functions in thinking mode; named selection on glm-5.3-flash is inconsistent.

  ▸ 展开子字段（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`).

• response_formatobject可选◐ Partially supported

  Response format configuration

  json_object works. json_schema works on deepseek-v4-flash and qwen3.8-flash but was not honored by 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

• ▸ 更多参数（49）

  • promptstring可选○ Currently ignored

    Accepted and ignored; Chat still requires messages and this field does not replace them.

  • 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可选○ Currently ignored

      If true, includes the transformed upstream request body in a debug chunk at the start of the stream. Only works with streaming mode.

      Accepted but currently has no effect. Streaming requests do not echo the upstream request body.

  • frequency_penaltynumber可选◐ Partially supported

    Frequency penalty (-2.0 to 2.0)

    Some requests take effect on deepseek-v4-flash and glm-5.3-flash; qwen3.8-flash rejects some values or faces with 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可选◐ Partially supported

    Return log probabilities

    Works on qwen3.8-flash; deepseek-v4-flash works only via /openai and glm-5.3-flash differs between faces. gemini-2.5-flash returns 400.

  • max_completion_tokensinteger可选◐ Partially supported

    Maximum tokens in completion

    Works on deepseek-v4-flash and glm-5.3-flash; small budgets on qwen3.8-flash may be ineffective or exceed limits.

  • metadataobject可选

    Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values)

  • min_pnumber可选○ Currently ignored

    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.

    Accepted but currently has no effect.

  • modalitiesarray可选

    Output modalities for the response. Supported values are "text", "image", and "audio".

  • modelsarray可选

    Models to use for completion

    Ordered fallback on an unknown primary, unavailable same-protocol line or upstream failure. models alone is accepted; response model and cost belong to the model that completes the request.

  • parallel_tool_callsboolean可选◐ Partially supported

    Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response.

    false works on qwen3.8-flash, is ignored by deepseek-v4-flash, and differs between faces on glm-5.3-flash.

  • pluginsarray可选◐ Partially supported

    Plugins you want to enable for this request, including their settings.

    Supports file-parser (pdf.engine native, mistral-ocr mapped to ocr, ocr, auto) and platform guardrails. Requests override account defaults but preserve locked settings. Unsupported plugins such as web, unknown engines and malformed configurations return 400 naming the field.

    ▸ 展开子字段（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可选◐ Partially supported

    Presence penalty (-2.0 to 2.0)

    An effect was observed on deepseek-v4-flash via /openai; some qwen3.8-flash requests return 400 and other effects are unobservable.

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

    ▸ 展开子字段（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可选◐ Partially supported

    When multiple model providers are available, optionally indicate your routing preference.

    Only supplier choice (order / only / ignore) is BYOK-only and returns 400; require_parameters is honoured and other options are accepted no-ops.

    ▸ 展开子字段（13）

    • allow_fallbacksboolean可选○ Currently ignored

      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.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

    • data_collectionstring可选○ Currently ignored

      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.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

      取值 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可选○ Unsupported

      List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request.

      Choosing suppliers (order / only / ignore) is BYOK-only; with platform credentials it returns 400 PROVIDER_SELECTION_NOT_ALLOWED.

    • max_priceobject可选○ Currently ignored

      The object specifying the maximum price you want to pay for this request. USD price per million tokens, for prompt and completion.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

    • onlyarray可选○ Unsupported

      List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request.

      Choosing suppliers (order / only / ignore) is BYOK-only; with platform credentials it returns 400 PROVIDER_SELECTION_NOT_ALLOWED.

    • orderarray可选○ Unsupported

      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.

      Choosing suppliers (order / only / ignore) is BYOK-only; with platform credentials it returns 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可选○ Currently ignored

      A list of quantization levels to filter the provider by.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

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

      Routes only to lines that can express every parameter; available with platform credentials.

    • sortstring | object可选○ Currently ignored

      The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

    • zdrboolean可选○ Currently ignored

      Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used.

      Accepted but currently has no effect (not supplier choice; available with platform credentials).

  • reasoningobject可选

    Configuration options for reasoning models

    ▸ 展开子字段（2）

    • effortstring可选◐ Partially supported

      Constrains effort on reasoning for reasoning models

      none reliably disables thinking only on qwen3.8-flash; deepseek-v4-flash and glm-5.3-flash do not honor it.

      取值 maxxhighhighmediumlowminimalnonenull
    • summarystring可选○ Currently ignored

      How detailed the reasoning summary should be.

      Accepted but currently has no effect. deepseek-v4-flash did not return the requested summary.

      取值 autoconcisedetailednull
  • reasoning_effortstring可选◐ Partially supported

    Shorthand for setting reasoning effort. Equivalent to setting reasoning.effort. Cannot be used simultaneously with reasoning.effort if they differ.

    none disables thinking on qwen3.8-flash; deepseek-v4-flash still thinks and glm-5.3-flash effort levels do not behave as expected.

    取值 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可选○ Currently ignored

    Random seed for deterministic outputs

    Accepted but currently has no effect. The same seed did not reproduce outputs on deepseek-v4-flash, glm-5.3-flash or qwen3.8-flash.

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

  • stopstring | array可选◐ Partially supported

    Stop sequences (up to 4)

    Works on qwen3.8-flash; deepseek-v4-flash and glm-5.3-flash may stop during reasoning and return empty content.

  • 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可选○ Currently ignored

      Deprecated: This field has no effect. Full usage details are always included.

      Accepted but currently has no effect. Usage is returned at the end whether true, false or omitted.

  • top_anumber可选○ Currently ignored

    Consider only tokens with "sufficiently high" probabilities based on the probability of the most likely token. Not all providers support this parameter.

    Accepted but currently has no effect.

  • top_kinteger可选◐ Partially supported

    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.

    No sampling effect was observed on tested models; deepseek-v4-flash via /model returns an error.

  • top_logprobsinteger可选◐ Partially supported

    Number of top log probabilities to return (0-20)

    Requires logprobs=true; support follows logprobs and the selected model.

  • 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可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • max_output_tokensinteger可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • thinkingobject可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • web_search_optionsobject可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • functionsarray可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • audioobject可选○ Currently ignored

    Accepted but currently has no effect. This applies to Chat Completions only.

  • ninteger可选◐ Partially supported

    Works on glm-5.3-flash; accepted but ignored on deepseek-v4-flash; qwen3.8-flash errors.

  • usageobject可选○ Currently ignored

    Accepted and ignored; usage is always returned, regardless of include.

  • transformsarray可选○ Currently ignored

    Accepted and ignored; no middle-out or other message transformation is performed.

  • deferred_toolsobject可选○ Currently ignored

    Accepted and ignored; the OpenRouter deferred-tool protocol is not implemented.

  • structured_outputsboolean可选○ Currently ignored

    Accepted and ignored; configure structured output with response_format, subject to its documented support.

  • include_reasoningboolean可选○ Currently ignored

    Accepted and ignored legacy alias; use reasoning subject to its documented support.

  • safe_promptboolean可选○ Currently ignored

    Accepted and ignored; the Mistral safe_prompt switch is not implemented.

  • raw_modeboolean可选○ Currently ignored

    Accepted and ignored; the Hyperbolic raw_mode switch is not implemented.

  • providerOptionsobject可选◐ Partially supported

    providerOptions.praxis.models uses the same ordered fallback as models. order/only require existing request-level BYOK credentials; non-BYOK requests return 400.

    ▸ 展开子字段（1）

    • praxisobject必填

      Platform options: ordered model fallback, request-level BYOK credentials and credential-gated provider selection.

Returns

200 chat.completion

With stream=true the reply streams as server-sent events (text/event-stream).

Unknown top-level fields are forwarded unchanged to same-protocol upstream providers, which decide whether to accept them. Declared fields still undergo type and range validation; invalid values return 400 naming the field.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring可选◐ Partially supported

  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.

  Verified on glm-5.3-flash and deepseek-flash; models without Responses support return 404.

• inputstring | array可选◐ Partially supported

  Input for a response request - can be a string or array of items

  Strings, message arrays, input_text, input_image and function round trips work. input_file errors on glm-5.3-flash and is ignored by deepseek-flash; managed file references return 400.

• streamboolean可选◐ Partially supported
  默认 false

  Whether to stream the response as server-sent events. Router support (partial): Works on deepseek-flash; glm-5.3-flash returns 400.

  Works on deepseek-flash; glm-5.3-flash returns 400.

• temperaturenumber可选◐ Partially supported

  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.

  Partly effective on glm-5.3-flash; 2 may produce empty or garbled text. Effects on deepseek-flash are unobservable.

• top_pnumber可选◐ Partially supported

  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.

  Sampling changes were observed on glm-5.3-flash; effects on deepseek-flash are unobservable.

• toolsarray可选◐ Partially supported

  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 works. web_search, code_interpreter, image_generation, mcp and computer_use are accepted but currently have no effect; file_search returns 404.

• tool_choicestring | object可选◐ Partially supported

  How the model picks tools: a mode string or a specific tool.

  auto works. required/named functions on deepseek-flash require reasoning.effort=none. allowed_tools is ignored by glm-5.3-flash and returns 422 on deepseek-flash.

  ▸ 展开子字段（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}.

• promptobject可选○ Unsupported

  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.

  No saved prompt templates are available; passing a template id returns 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.

• backgroundboolean可选◐ Partially supported

  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.

  Works on deepseek-flash; glm-5.3-flash returns 400. Combining background with stream returns JSON.

• includearray可选◐ Partially supported

  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 returns logprobs, but reasoning.encrypted_content is only a placeholder. glm-5.3-flash accepts but currently ignores include.

• ▸ 更多参数（21）

  • instructionsstring可选

    System or developer instructions inserted at the start of the context. Router support (supported): Verified to take effect.

    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.

    A positive value controls the output budget; zero returns 400.

  • metadataobject可选◐ Partially supported

    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.

    Echoed on glm-5.3-flash; accepted but currently ignored by deepseek-flash, with empty metadata in both creation and retrieval.

  • parallel_tool_callsboolean可选◐ Partially supported

    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 permits multiple calls; false is accepted but currently has no effect and may still return multiple calls.

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

    The platform combines ancestor inputs and outputs with the current input. We remove previous_response_id before calling the upstream. A missing live copy or a response owned by another tenant returns 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.

    ▸ 展开子字段（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可选◐ Partially supported

      How much reasoning the model should spend.

      none disables thinking on deepseek-flash; other levels are not monotonic. glm-5.3-flash accepts but ignores it, including 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可选◐ Partially supported

      How detailed the reasoning summary should be.

      concise occasionally yields a summary on glm-5.3-flash, while auto/detailed did not. deepseek-flash accepts but ignores it.

      取值 autoconcisedetailednull
    • 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可选
    默认 "auto"

    Requested service tier; its effect is currently unobservable.

    取值 autodefaultfastflexpriorityscalenull
  • storeboolean可选
    默认 true

    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 stores the response for retrieval; false does not, and retrieval returns 404.

  • textobject可选

    Text output configuration including format and verbosity

    ▸ 展开子字段（2）

    • formatobject可选◐ Partially supported

      Text response format configuration

      json_object and json_schema work with sufficient budget; text intermittently returns 400 on glm-5.3-flash and works on deepseek-flash.

    • verbositystring可选○ Currently ignored

      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.

      Accepted but currently has no effect. No verbosity effect was observed on glm-5.3-flash or deepseek-flash.

      取值 lowmediumhighxhighmaxnull
  • top_logprobsinteger可选◐ Partially supported

    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.

    Works on deepseek-flash with values 0–20; glm-5.3-flash returns empty 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可选

    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.

    Conversation history is included in input and response items are appended; cannot be combined with 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可选○ Unsupported

    Recognized official field; access programs are not implemented and return 400 explicitly stating that the parameter is not supported.

Returns

200 response

With stream=true the reply streams as server-sent events (text/event-stream).

Unknown top-level fields are forwarded unchanged to same-protocol upstream providers, which decide whether to accept them. Declared fields still undergo type and range validation; invalid values return 400 naming the field.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 response

Reads a stored response by ID. If it was created with store set to false we did not store it, and the read returns 404 response_not_found; after the retention period (30 days by default) the read returns the same 404.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 response

Deletes a stored response by ID immediately. If it was created with store set to false we did not store it, and the delete returns 404 response_not_found.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 response

Available only for responses created with background:true and routed to a model that can generate in the background. Cancel is idempotent — repeated calls return the same terminal response. Cancelling stops us reading the upstream stream; it cannot guarantee that compute already sent upstream stops, and usage is billed for what was actually received. Calling cancel on a non-background (synchronous) response returns 404 object_not_found if the response id does not exist (not stored, expired or wrong id), or 400 native_responses_operation_unsupported if the response exists but its provider does not declare cancel support (none of the upstreams we connect declares it for synchronous responses). Neither case is the not-implemented 501.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 list

Lists the input items of a stored response. Supports limit (1–100, default 20), order (asc/desc, default desc, as in the official API) and cursor pagination by item id with after; has_more / first_id / last_id match the page actually returned, so you can page through without gaps or repeats. Every item carries a server-issued id (msg_ for messages, and each of function_call / function_call_output / reasoning has its own prefix); older data stored before ids existed gets deterministic ids on read, without a destructive migration, so repeated reads with the same cursor stay stable. For a response created with previous_response_id, the list shows the full resolved input: the input and output items of the earlier responses in the chain plus the input submitted this turn; if an ancestor response was not stored on the platform (for example created with store false) or has expired, only this turn's own input is listed. If the response was created with store set to false we did not store it, and the list returns 404 response_not_found.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  The model to use for embeddings

  Verified to take effect.

• inputstring | array必填◐ Partially supported

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

  Text and text arrays work; integer token arrays return 400. Images work only on qwen3-vl-embedding and doubao-embedding-vision; a 16-item text-embedding-3-small batch returns 400.

• dimensionsinteger可选◐ Partially supported

  The number of dimensions for the output embeddings

  Only text-embedding-3-small and qwen3-vl-embedding support the tested 256 dimensions; text-embedding-3-small also supports 512, while 100 returns 400. 256 returns 400 on bge-m3, qwen3-embedding-0.6b and doubao-embedding-vision.

• encoding_formatstring可选

  The format of the output embeddings

  Both float and base64 are supported; base64 encodes the vector bytes.

  取值 floatbase64
• input_typestring可选◐ Partially supported

  The type of input (e.g. search_query, search_document)

  query/document work on bge-m3 and qwen3-embedding-0.6b; search_query returns 400. text-embedding-3-small accepts but currently ignores this field.

• providerobject可选◐ Partially supported

  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 and qwen3-embedding-0.6b return 400; text-embedding-3-small accepts it, with an unobservable effect.

  ▸ 展开子字段（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可选◐ Partially supported

  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 and qwen3-embedding-0.6b return 400; text-embedding-3-small accepts it, with an unobservable effect.

• traceobject可选◐ Partially supported

  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 and qwen3-embedding-0.6b return 400; text-embedding-3-small accepts it, with an unobservable effect.

  ▸ 展开子字段（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可选◐ Partially supported

  A unique identifier for the end-user

  bge-m3 and qwen3-embedding-0.6b return 400; text-embedding-3-small accepts it, with an unobservable effect.

Returns

200 list

Unknown top-level fields are forwarded unchanged to same-protocol upstream providers, which decide whether to accept them. Declared fields still undergo type and range validation; invalid values return 400 naming the field.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  Rerank model id; list candidates with listModels?type=reranking. Router support (supported): Verified to take effect.

  Verified to take effect.

• querystring必填

  Query to rank the documents against, at least 1 character. Router support (supported): Verified to take effect.

  Verified to take effect.

• documentsarray必填◐ Partially supported

  Documents to rank, as plain strings, at least one. Router support (partial): Only string arrays are supported; object arrays return 400.

  Only string arrays are supported; object arrays return 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.

  Controls returned result count; zero returns 400.

• return_documentsboolean可选○ Unsupported

  bge-reranker-base returns 400; only model, query, documents and top_n are supported.

• max_tokens_per_docinteger可选○ Unsupported

  bge-reranker-base returns 400; only model, query, documents and top_n are supported.

• rank_fieldsarray可选○ Unsupported

  bge-reranker-base returns 400; only model, query, documents and top_n are supported.

• max_chunks_per_docinteger可选○ Unsupported

  bge-reranker-base returns 400; only model, query, documents and top_n are supported.

• userstring可选○ Unsupported

  bge-reranker-base returns 400; only model, query, documents and top_n are supported.

Returns

200

Standard request fields; unrepresentable parameters return input_not_representable.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  Speech model id, for example `melotts` or `aura-2-en`; list candidates with listModels?type=speech. Router support (supported): Verified to take effect.

  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 supports input, lang and response_format=wav; text/prompt aliases also work.

• response_formatstring可选◐ Partially supported

  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 supports WAV only. aura-2-en supports mp3/opus/flac/wav/pcm; aac errors.

  取值 mp3opusflacwavpcm
• promptstring可选

  MeloTTS alias for input; input then text take precedence.

  Alias for input; input takes precedence.

• voicestring | object可选◐ Partially supported

  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.

  Only aura-2-en supports native speaker names such as thalia/apollo/orion/luna/zeus; alloy and objects are unsupported. Omit on melotts.

  ▸ 展开子字段（1）

  • 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可选○ Unsupported

  Accepted by the protocol; these Cloudflare models reject it with 400.

  Both melotts and aura-2-en return 400.

• speednumber可选◐ Partially supported
  默认 1

  Only 1 is representable by these Cloudflare models.

  Only the default value 1 is accepted; other speeds are unsupported and return errors.

• stream_formatstring可选◐ Partially supported
  默认 "audio"

  Only audio is supported; the response is buffered binary audio.

  audio works; sse returns 400.

  取值 audio
• textstring可选

  Native alias for input; input wins.

  Alias for input; input takes precedence.

• speakerstring可选◐ Partially supported

  Aura alias for voice; voice wins.

  aura-2-en supports native speaker names; melotts returns 400.

• ▸ 更多参数（5）

  • langstring可选◐ Partially supported

    MeloTTS language; defaults to en. Use this field to select language; voice is not supported by MeloTTS.

    melotts supports en/fr/es/zh; ja/ko error. aura-2-en does not support lang.

    取值 enfreszhjako
  • encodingstring可选◐ Partially supported

    Aura native encoding; response_format wins; mulaw/alaw/aac return 400 when used to select the format.

    melotts supports linear16 only; aura-2-en supports tested linear16/flac encodings while mulaw returns 400. response_format takes precedence.

    取值 linear16flacmulawalawmp3opusaac
  • containerstring可选◐ Partially supported

    Aura container; response_format wins.

    aura-2-en supports opus+ogg and linear16+none; container=wav returns 400. melotts does not support this field.

    取值 nonewavogg
  • sample_rateinteger可选◐ Partially supported

    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 only: tested wav at 8000/16000 and pcm at 24000. 44100 and custom mp3 rates error. Unsupported on melotts.

  • bit_rateinteger可选◐ Partially supported

    Aura bit rate in bits per second. MP3 supports 32000/48000; Opus supports 4000–650000. Other accepted formats reject this control.

    aura-2-en only: tested mp3 at 32000/48000 and opus at 64000; mp3=64000 errors. Unsupported on melotts.

Returns

200

melotts outputs WAV and supports input (including text/prompt aliases), lang and default audio options; aura-2-en uses native speaker names. See per-field limits below.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

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

  Verified to take effect.

• temperaturenumber可选○ Unsupported

  Both whisper-large-v3-turbo and qwen3-asr-flash return 400.

• response_formatstring可选◐ Partially supported
  默认 "json"

  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 work on both; verbose_json works only on whisper-large-v3-turbo. srt/vtt return 400.

  取值 jsontextverbose_json
• promptstring可选◐ Partially supported

  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.

  Vocabulary hints work on whisper-large-v3-turbo only; qwen3-asr-flash returns 400.

• filestring必填

  Audio file to transcribe, uploaded as multipart/form-data. Router support (supported): Verified to take effect.

  Verified to take effect.

• languagestring可选◐ Partially supported

  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.

  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.

• timestamp_granularities[]array可选◐ Partially supported

  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.

  Only whisper-large-v3-turbo supports segment with verbose_json. word returns 400; qwen3-asr-flash does not support timestamps.

Returns

200

Standard request fields; unrepresentable parameters return input_not_representable.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  Image model id; list candidates with listModels?type=image. Router support (supported): Verified to take effect.

  Verified to take effect.

• response_formatstring可选◐ Partially supported

  Image response encoding. Only b64_json is accepted; url returns 400.

  gpt-image-2 supports b64_json; url returns 400.

  取值 b64_json
• promptstring必填

  Text description of the image to generate. Router support (supported): Verified to take effect.

  Verified to take effect.

• ninteger可选
  默认 1

  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.

  Controls image count; zero returns 400 and values 1–10 are accepted.

• sizestring可选◐ Partially supported

  Size of the generated images. Router support (partial): gpt-image-2 supports tested 1024x1024 and 1024x1536 sizes; 512x512 returns 400.

  gpt-image-2 supports tested 1024x1024 and 1024x1536 sizes; 512x512 returns 400.

  取值 1024x10241024x15361536x1024auto
• qualitystring可选

  Quality of the generated images. Router support (supported): Verified to take effect.

  Verified to take effect.

  取值 lowmediumhighauto
• backgroundstring可选

  transparent returns a transparent PNG on gpt-image-2.

• output_formatstring可选

  jpeg returns JPEG on gpt-image-2.

Returns

200

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  Image model id; list candidates with listModels?type=image. Router support (supported): Verified to take effect.

  Verified to take effect.

• promptstring必填

  Text description of the desired edit. Router support (supported): Verified to take effect.

  Verified to take effect.

• imagearray必填

  Source images as base64 data URLs.

• maskstring可选○ Unsupported

  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.

  The tested PNG mask returns 400 and is currently unusable.

• nnumber可选

  Number of edited images to generate. Router support (supported): Verified to take effect.

  Verified to take effect.

• sizestring可选

  Size of the edited images. Router support (supported): Verified to take effect.

  Verified to take effect.

• image[]array可选

  Source images, uploaded as multipart files. Router support (supported): Accepts multipart files or JSON data URLs.

  Accepts multipart files or JSON data URLs.

Returns

200

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填

  OCR model ID, for example glm-ocr.

  Verified to take effect.

• documentobject必填

  Choose document_url, image_url (HTTPS or data URL), or {type: file, file_id: string}.

  Supports PDF data URLs, image_url and uploaded file_id; remote URLs must be downloadable.

  ▸ 展开子字段（5）

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

  Zero-based page selection with deduplication; out-of-range pages error.

• include_image_base64boolean可选◐ Partially supported

  Include extracted images as base64.

  glm-ocr accepts false only; true returns 400.

• table_formatstring可选◐ Partially supported

  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 accepts markdown or null only; html returns 400.

• extract_headerboolean可选○ Unsupported

  Whether to extract page headers separately into `header`. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

  Unsupported on glm-ocr; passing it returns 400.

• extract_footerboolean可选○ Unsupported

  Whether to extract page footers separately into `footer`. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

  Unsupported on glm-ocr; passing it returns 400.

• bbox_annotation_formatobject可选○ Unsupported

  Structured image annotations; OCR requires json_schema. Availability depends on the model.

  Unsupported on glm-ocr; passing it returns 400.

  ▸ 展开子字段（2）

  • typestring可选

    Response format type of the annotation.

    取值 textjson_objectjson_schema
  • json_schemaobject可选

    JSON Schema the annotation of each detected image region must follow.

• document_annotation_formatobject可选○ Unsupported

  Structured document annotation; OCR requires json_schema. Availability depends on the model.

  Unsupported on glm-ocr; passing it returns 400.

  ▸ 展开子字段（2）

  • typestring可选

    Response format type of the annotation.

    取值 textjson_objectjson_schema
  • json_schemaobject可选

    JSON Schema the document annotation must follow.

• document_annotation_promptstring可选○ Unsupported

  Instruction for the document annotation, which says what to extract. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

  Unsupported on glm-ocr; passing it returns 400.

• ▸ 更多参数（4）

  • image_limitinteger可选○ Unsupported

    Maximum number of images to extract per document; null for no limit. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

    Unsupported on glm-ocr; passing it returns 400.

  • image_min_sizeinteger可选○ Unsupported

    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.

    Unsupported on glm-ocr; passing it returns 400.

  • include_blocksboolean可选○ Unsupported

    Whether to return layout `blocks` for each page. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

    Unsupported on glm-ocr; passing it returns 400.

  • confidence_scores_granularitystring可选○ Unsupported

    Level at which confidence scores are returned. Router support (unsupported): Unsupported on glm-ocr; passing it returns 400.

    Unsupported on glm-ocr; passing it returns 400.

Returns

200

Uses the Mistral OCR request and response shape at /model/v1/ocr only. model is required; document accepts document_url or image_url (HTTPS or base64 data URL), or `{type:"file", file_id:"<uploaded ID>"}` to read a File owned by the authenticated tenant. The file_id read limit is 24 MiB (25,165,824 bytes: the shared 96 MiB memory budget divided by four). Larger files return 413 with guidance to use HTTPS document_url (PDF limit: 50 MiB). PNG/JPEG remain limited to 10 MiB; the bytes determine the type. Missing and other-tenant files both return 404. pages is an array of zero-based page indices; for images, only `[0]` is supported when supplied. File read failures are not billed, and request logs retain only the file_id, never the file content. Optional features depend on the model; unsupported options return 400. Errors use problem+json; providerOptions.praxis is not supported here.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring可选◐ Partially supported

  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.

  Select a registered video model explicitly, for example wan2.7-t2v (size=1280x720, seconds=4). Capability preflight errors are reported before creation.

• promptstring必填

  Text description of the video, at least 1 character. Router support (supported): Controls video content; missing or empty values return 400.

  Controls video content; missing or empty values return 400.

• secondsstring | integer可选

  When both are supplied, seconds overrides duration.

  Duration works on wan2.7-t2v; malformed values or values outside model capabilities return 400 during preflight.

• durationinteger可选

  Length of the video in whole seconds. `seconds` takes precedence when both are given.

• sizestring可选◐ Partially supported

  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.

  Subject to model capability preflight. Earlier wan2.7-t2v samples always produced 1280x720; accepted sizes are not guaranteed pixel-for-pixel.

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

    false produces no audio track on wan2.7-t2v; the default output includes audio.

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

Returns

200

Billed per second of output video; GET /model/v1/models exposes pricing.video_second in USD per second.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

  Pagination works; limit is 1–100, order is asc/desc, and after must refer to an existing job.

• limitinteger可选
  默认 20

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

  Pagination works; limit is 1–100, order is asc/desc, and after must refer to an existing job.

• orderany可选
  默认 "desc"

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

  Pagination works; limit is 1–100, order is asc/desc, and after must refer to an existing job.

  取值 ascdesc

Returns

200

Billed per second of output video; GET /model/v1/models exposes pricing.video_second in USD per second.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200

Billed per second of output video; GET /model/v1/models exposes pricing.video_second in USD per second.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

• 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可选◐ Partially supported
  默认 "video"

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

  video and thumbnail work; spritesheet returns 400.

  取值 videothumbnailspritesheet
• indexinteger可选◐ Partially supported

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

  Video supports index=0 only; positive or negative indices return 400. With variant=thumbnail, index is accepted but currently ignored.

Returns

200

Billed per second of output video; GET /model/v1/models exposes pricing.video_second in USD per second.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200

Billed per second of output video; GET /model/v1/models exposes pricing.video_second in USD per second.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填◐ Partially supported

  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 and claude-opus-5 can be called; deepseek-v4-flash returns 400 on this face.

• messagesarray必填◐ Partially supported

  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.

  Text and tool round trips work. Managed document file_id returns 400; qwen3.8-flash can read inline PDFs. Images have model-specific size limits.

  ▸ 展开子字段（2）

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

  Limits output tokens, including reasoning.

• streamboolean可选◐ Partially supported

  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.

  Content and tool streaming work; extra message_delta events may precede content and message_start usage is zero.

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

  Verified to take effect.

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

  Verified to take effect.

• tool_choiceobject可选◐ Partially supported

  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.

  All four modes work on qwen3.8-flash; deepseek-v4-pro ignores any/tool/none and glm-5.3-flash ignores none.

  ▸ 展开子字段（3）

  • typestring必填

    Disable tool calls for this request.

    取值 none
  • disable_parallel_tool_useboolean可选○ Currently ignored

    Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.

    Accepted but currently has no effect. true may still return multiple tool calls.

  • namestring必填

    The name of the tool to use.

• cache_controlobject可选◐ Partially supported

  Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  Implicit cache hits occur on deepseek-v4-pro, qwen3.8-flash and glm-5.3-flash, but do not establish that the marker controls caching. No hits were observed on claude-opus-5, and ttl=1h had no observed effect.

  ▸ 展开子字段（2）

  • typestring必填

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

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

• ▸ 更多参数（16）

  • containerstring | object可选○ Currently ignored

    Accepted and ignored; the platform does not implement container.

    ▸ 展开子字段（2）

    • idstring可选

      Container id

    • skillsarray可选

      List of skills to load in the container

  • inference_geostring可选○ Currently ignored

    Accepted and ignored; the platform does not implement inference_geo.

  • metadataobject可选◐ Partially supported

    Body param: An object describing metadata about the request.

    Accepts metadata; metadata.user_id is carried on same-protocol lines without promising an upstream echo.

    ▸ 展开子字段（1）

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

    ▸ 展开子字段（2）

    • effortstring可选◐ Partially supported

      All possible effort levels.

      Only high/xhigh work on deepseek-v4-pro; other levels return 400. All levels return 400 on qwen3.8-flash. glm-5.3-flash accepts levels but usage is not monotonic.

    • formatobject可选◐ Partially supported

      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 works on deepseek-v4-pro and qwen3.8-flash; glm-5.3-flash returns 400 when combined with thinking.

  • service_tierstring可选○ Currently ignored

    Accepted and ignored; the platform does not implement service_tier.

  • stop_sequencesarray可选◐ Partially supported

    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.

    Works on deepseek-v4-pro and qwen3.8-flash; glm-5.3-flash truncates text but does not report accurate stop_reason/stop_sequence.

  • thinkingobject可选◐ Partially supported

    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 works on deepseek-v4-pro and qwen3.8-flash; any thinking parameter returns 400 on glm-5.3-flash. adaptive also returns 400 on tested deepseek-v4-pro and qwen3.8-flash.

    ▸ 展开子字段（3）

    • budget_tokensnumber必填◐ Partially supported

      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.

      Accepted on deepseek-v4-pro and qwen3.8-flash but is not a reliable upper bound; glm-5.3-flash returns 400.

    • typestring必填

      Let the model choose its reasoning budget, subject to output_config.effort when supplied.

      取值 adaptive
    • displaystring可选○ Currently ignored

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

      Accepted but currently has no effect. omitted still returns the full thinking content.

  • top_knumber可选

    Sample only from the top K options for each token.

  • context_managementobject可选○ Currently ignored

    Accepted and ignored; the platform does not implement context_management.

  • diagnosticsobject可选○ Currently ignored

    Accepted and ignored; the platform does not implement diagnostics.

  • mcp_serversarray可选○ Currently ignored

    Accepted and ignored; the platform does not implement mcp_servers.

  • speedstring可选○ Currently ignored

    Accepted and ignored; the platform does not implement speed.

  • output_formatobject可选○ Currently ignored

    Accepted and ignored legacy field; use output_config.format for structured output.

  • compactionobject可选○ Unsupported

    Recognized compaction; not implemented, and returns 400 explicitly stating that the parameter is not supported.

  • fallback_credit_tokenstring可选○ Unsupported

    Recognized fallback_credit_token; not implemented, and returns 400 explicitly stating that the parameter is not supported.

  • fallbacksstring可选○ Unsupported

    Recognized fallbacks; not implemented, and returns 400 explicitly stating that the parameter is not supported.

Returns

200

With stream=true the reply streams as server-sent events (text/event-stream).

Unknown top-level fields are forwarded unchanged to same-protocol upstream providers, which decide whether to accept them. Declared fields still undergo type and range validation; invalid values return 400 naming the field.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• modelstring必填○ Currently ignored

  Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  Accepted but currently has no effect. The estimate is model-independent, even with a missing or unknown model.

• messagesarray必填◐ Partially supported

  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.

  Character-based estimate only, not exact model tokenization.

  ▸ 展开子字段（2）

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

  Included in the estimate.

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

  Included in the estimate.

• tool_choiceobject可选○ Currently ignored

  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.

  Accepted but currently has no effect. Does not change the count.

  ▸ 展开子字段（3）

  • typestring必填

    Disable tool calls for this request.

    取值 none
  • 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可选○ Currently ignored

  Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  Accepted but currently has no effect. Does not change the count.

  ▸ 展开子字段（2）

  • typestring必填

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

    取值 ephemeral
  • 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可选○ Currently ignored

  Body param: Configuration options for the model's output, such as the output format.

  Accepted but currently has no effect. Does not change the count.

  ▸ 展开子字段（2）

  • 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可选○ Currently ignored

  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.

  Accepted but currently has no effect. Does not change the count.

  ▸ 展开子字段（3）

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

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

Returns

200

Returns a model-family-calibrated estimate, including Chinese text and tool definitions, with the response header x-praxis-token-count: estimated. Do not use it as an exact usage or billing count.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

  Filter by comma-separated model types; invalid values return 400 with the legal values.

• output_modalitiesarray可选

  query: Match any comma-separated output modality; all disables modality filtering. Combined with type using AND.

  Match any comma-separated output modality; all disables modality filtering. Combined with type using AND.

• limitstring可选○ Currently ignored

  query: Accepted for compatibility and ignored: this endpoint always returns the full model catalog. Filter with type and output_modalities instead.

  Accepted but currently has no effect; this endpoint returns the full model catalog.

• qstring可选○ Currently ignored

  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.

  Accepted but currently has no effect; this endpoint returns the full model catalog.

Returns

200 list

OCR models have type ocr and pricing.page as a decimal string in USD per page, a Praxis extension to the Vercel model list shape; the four token prices are 0. Other models omit pricing.page.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 model

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

• idstring必填◐ Partially supported

  query: Generation ID from the X-Praxis-Generation-Id response header of the model request.

  Use X-Praxis-Generation-Id from a /model response header; response-body ids and X-Request-Id return 404.

Returns

200

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request body

• itemsarray可选

  Initial items, at most 20 per request. Router support (supported): Verified to take effect.

  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.

  Verified to take effect.

Returns

200 conversation

Creates a conversation, optionally with initial items (up to 20 per call) and metadata. Conversations are tenant-partitioned; the creating tenant is the only one that can reference it.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 conversation

Reads a conversation by ID. A missing or foreign-tenant conversation answers 404 conversation_not_found.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

  Verified to take effect.

Returns

200 conversation

Replaces a conversation's metadata wholesale — it does not merge with existing metadata.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

  Verified to take effect.

Returns

200 list

Appends items to a conversation (up to 20 per call) and returns exactly the appended items.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 list

Lists a conversation's items in creation order, with limit/after/order pagination.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200

Reads a single conversation item by ID.

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 conversation

Deletes one conversation item and returns the conversation object (not the deleted item).

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes

Request parameters

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

Returns

200 conversation.deleted

Deletes a conversation. Afterwards neither it nor its items can be referenced again (including as the conversation parameter of Responses create).

Platform errors (auth, rate limits, validation) and OCR errors use problem+json; other model call errors follow the endpoint's own format (OpenAI or Anthropic) — see error codes