Responses

POST /v1/responses  compatible  语义操作 generate  契约修订 2

状态语义：stateless by default; background=true defers one generation to a project-owned record with a 24 hour TTL and a 15 minute cool-off after first retrieval; the remaining stateful fields are rejected before provider I/O

查看原始契约偏差（英文）

这些是源码契约中的逐条证据。日常接入先看本页示例、字段表和 Profile 覆盖矩阵；排查兼容性边界时 再展开核对原文。

• input_items, Conversations, and webhooks are unavailable; retrieval, cancellation and deletion serve deferred submissions alone
• store defaults to false and store=true is rejected even alongside background=true, because store asserts that the provider retains the Response and Halro’s upstream retains nothing (ADR 0021)
• background=true is enabled per Project and refused with unsupported_feature where the Project has not enabled it, because a deferred answer is written to disk and that is a decision about what the data directory holds
• a background submission carries at most 256 KiB of request body, which is below the gateway’s own request ceiling: the same body sent synchronously is accepted and sent with background=true is refused, because the deferred body is stored rather than forwarded
• a background submission does not survive a gateway restart: a deferred response has no upstream handle, so a request in flight when the process dies is failed and settled conservatively
• a deferred answer larger than 1 MiB is failed rather than stored, and the request was still billed: the ceiling is on what may be kept, and nothing can measure an answer before the upstream produces it
• a background submission whose Project is at its TPM or concurrency ceiling waits in the queue rather than being refused; only the queue depth and the 24 hour TTL bound that wait
• one deferred attempt is bounded by the same route_total_timeout a synchronous attempt runs under; exceeding it fails the request, which was still billed
• strict function tools, reasoning output, and streaming tools are rejected
• tools[].type=web_search is the one hosted tool accepted; it is routed against the provider_executed_tools capability and served only by the OpenAI Responses profile, and code_interpreter and file_search stay rejected because both are provider-side state
• request instructions, tool definitions, tool choice, and structured schema bodies are returned as conservative null, empty, or default response metadata because the original Responses object has not passed through outbound redaction
• portable requests are translated through the selected profile’s existing generation primitive
• unknown fields and unsupported item types are rejected before provider I/O

默认请求仍是无状态的：省略 store 等同于 store: false，store=true、 previous_response_id 和 conversation 会在到达 Provider 之前被拒。Project 明确启用延迟响应后， background: true 会把一次生成提交到 Halro 自己的有界队列。Idempotency-Key 可选但强烈建议使用； 它不是 Provider 托管的 Response，也不提供多轮会话。

请求示例

curl

curl https://halro.example.com/v1/responses \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "chat", "max_output_tokens": 256,
        "input": "用一句话介绍 Halro" }'

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://halro.example.com/v1", api_key=os.environ["HALRO_GATEWAY_KEY"],
                timeout=60.0, max_retries=0)
# 不要传 store / previous_response_id：它们会在到达 Provider 之前被拒。
response = client.responses.create(
    model="chat", max_output_tokens=256,
    input="用一句话介绍 Halro",
)
print(response.output_text)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://halro.example.com/v1", apiKey: process.env.HALRO_GATEWAY_KEY,
  timeout: 60_000, maxRetries: 0,
});
// 不要传 store / previous_response_id：它们会在到达 Provider 之前被拒。
const response = await client.responses.create({
  model: "chat", max_output_tokens: 256,
  input: "用一句话介绍 Halro",
});
console.log(response.output_text);

SDK 默认会自动重试

官方 SDK 默认会重试 2 次。Halro 在发出上游请求之前就把预算预留落盘，因此客户端的 静默重试会产生多次独立的预留与结算。示例把它关掉，由你自己决定重试策略 —— 见重试、超时与幂等。

请求头

• Authorization
• Content-Type
• Idempotency-Key when submitting with background=true

请求字段

怎么读这张表

第 2 列沉默不等于支持 —— 契约只记录已声明的限制，没列出的 Profile 是「未声明限制」， 不是「已验证支持」。第 3 列是组合级限制：某些拒绝规则在字段粒度上表达不出来 （例如某个 Profile 拒绝「带工具的流式请求」，而 tools 与 stream 单看都支持）。 字段的类型、是否必填与语义说明当前不在契约里，见页脚说明。

请求字段

字段	不支持该字段的 Provider Profile	组合级限制
model	—	1 见脚注 1
input	—	—
input[].type	—	—
input[].role	—	—
input[].content	—	—
input[].call_id	—	—
input[].name	—	—
input[].arguments	—	—
input[].output	—	—
input[].content[].type	—	—
input[].content[].text	—	—
input[].content[].detail	anthropic.messages.2023-06-01、anthropic.subscription.messages.v1、bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、bedrock.mantle.anthropic.messages.v1、minimax.anthropic.messages.v1、kimi.anthropic.messages.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1、kimi.code.anthropic.messages.v1	—
instructions	—	—
reasoning	—	2 见脚注 2
stream	—	—
store	—	—
temperature	kimi.chat.v1、kimi.anthropic.messages.v1、kimi.responses.v1、kimi.code.openai.chat.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1、kimi.code.anthropic.messages.v1	3 见脚注 3
top_p	kimi.chat.v1、kimi.anthropic.messages.v1、kimi.responses.v1、kimi.code.openai.chat.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1、kimi.code.anthropic.messages.v1	4 见脚注 4
max_output_tokens	—	—
tools	bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.responses.v1、bedrock.mantle.openai.responses.v1	5 见脚注 5
tools[].type	—	6 见脚注 6
tools[].name	—	7 见脚注 7
tools[].description	—	8 见脚注 8
tools[].parameters	—	9 见脚注 9
tools[].strict	—	10 见脚注 10
tool_choice	bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、kimi.chat.v1、kimi.code.openai.chat.v1	11 见脚注 11
parallel_tool_calls	deepseek.chat.v1、bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、minimax.chat.v1、minimax.responses.v1、kimi.chat.v1、kimi.responses.v1、kimi.code.openai.chat.v1、minimax.cn.subscription.openai.chat.v1、minimax.global.subscription.openai.chat.v1	12 见脚注 12
text.format	anthropic.messages.2023-06-01、anthropic.subscription.messages.v1、deepseek.chat.v1、bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1、minimax.anthropic.messages.v1、minimax.chat.v1、minimax.responses.v1、kimi.anthropic.messages.v1、kimi.code.openai.chat.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1、minimax.cn.subscription.openai.chat.v1、minimax.global.subscription.openai.chat.v1、kimi.code.anthropic.messages.v1	13 见脚注 13
text.format.type	—	—
text.format.name	—	—
text.format.description	—	—
text.format.schema	—	—
text.format.strict	—	—
user	anthropic.messages.2023-06-01、anthropic.subscription.messages.v1、bigmodel.cn.chat-embeddings.v1、bigmodel.global.chat.v1、bigmodel.cn.coding.chat.v1、bigmodel.global.coding.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1、minimax.anthropic.messages.v1、minimax.chat.v1、minimax.responses.v1、kimi.chat.v1、kimi.anthropic.messages.v1、kimi.responses.v1、kimi.code.openai.chat.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1、minimax.cn.subscription.openai.chat.v1、minimax.global.subscription.openai.chat.v1、kimi.code.anthropic.messages.v1	—
background	—	—

门面层直接拒绝的字段

这些字段在到达任何 Provider 之前就会被拒。照搬 OpenAI 文档最容易撞上的就是它们：

• store=true
• previous_response_id
• conversation
• background=true with stream=true
• prompt
• metadata
• include
• context_management
• service_tier
• truncation
• max_tool_calls
• prompt_cache_key
• prompt_cache_options
• prompt_cache_retention
• safety_identifier
• stream_options
• top_logprobs
• reasoning
• input[].id
• input[].type=unsupported
• tools[].type!=function
• tools[].strict=true
• stream=true with tools

响应字段

id object created_at completed_at status background error incomplete_details instructions max_output_tokens model output output[].id output[].type output[].status output[].role output[].content output[].call_id output[].name output[].arguments output[].content[].type output[].content[].text output[].content[].refusal output[].content[].annotations output[].content[].logprobs parallel_tool_calls previous_response_id reasoning store temperature text tool_choice tools top_p truncation usage usage.input_tokens usage.output_tokens usage.total_tokens

流事件

response.created response.in_progress response.output_item.added response.content_part.added response.output_text.delta response.output_text.done response.content_part.done response.output_item.done response.completed response.incomplete error

Provider Profile 契约覆盖与本构建可用性

端点成熟度不提升单个 Profile

顶部的 compatible 徽章说的是端点，不是下面每一行。每行的成熟度取自该 Profile 自己的覆盖记录。

本页存在成熟度分歧

bigmodel.cn.chat-embeddings.v1 的成熟度是 experimental，低于端点的 compatible。 bigmodel.global.chat.v1 的成熟度是 experimental，低于端点的 compatible。 bigmodel.cn.coding.chat.v1 的成熟度是 experimental，低于端点的 compatible。 bigmodel.global.coding.chat.v1 的成熟度是 experimental，低于端点的 compatible。 kimi.code.openai.chat.v1 的成熟度是 experimental，低于端点的 compatible。 minimax.cn.subscription.anthropic.messages.v1 的成熟度是 experimental，低于端点的 compatible。 minimax.global.subscription.anthropic.messages.v1 的成熟度是 experimental，低于端点的 compatible。 minimax.cn.subscription.openai.chat.v1 的成熟度是 experimental，低于端点的 compatible。 minimax.global.subscription.openai.chat.v1 的成熟度是 experimental，低于端点的 compatible。 kimi.code.anthropic.messages.v1 的成熟度是 experimental，低于端点的 compatible。

有契约，不代表本构建可创建

bedrock.runtime.converse.text.v1、kimi.responses.v1、minimax.cn.subscription.anthropic.messages.v1、minimax.global.subscription.anthropic.messages.v1 已实现且保留在兼容性契约中，但被 Halro 08af8c8b0b10 的 served Profile matrix 隐藏，Admin 写路径也会拒绝创建。 新实例不能把这些 Profile 配置成 Deployment；已有记录只保留启动与删除通道。

Provider Profile 契约覆盖与本构建可用性

Provider Profile	成熟度	本构建	不支持的请求字段
openai.chat-embeddings.v1	compatible	可创建	未声明
openai.responses.v1	compatible	可创建	未声明
anthropic.messages.2023-06-01	compatible	可创建	text.format、user、input[].content[].detail
anthropic.subscription.messages.v1	compatible	默认关闭：需 provider_subscriptions.anthropic_claude	text.format、user、input[].content[].detail
azure-openai.chat-embeddings.v1	compatible	可创建	未声明
deepseek.chat.v1	compatible	可创建	parallel_tool_calls、text.format
bigmodel.cn.chat-embeddings.v1	experimental	可创建	parallel_tool_calls、tools、text.format、tool_choice、user、input[].content[].detail
bigmodel.global.chat.v1	experimental	可创建	parallel_tool_calls、tools、text.format、tool_choice、user、input[].content[].detail
bigmodel.cn.coding.chat.v1	experimental	可创建	parallel_tool_calls、tools、text.format、tool_choice、user、input[].content[].detail
bigmodel.global.coding.chat.v1	experimental	可创建	parallel_tool_calls、tools、text.format、tool_choice、user、input[].content[].detail
openai-compatible.chat-embeddings.v1	compatible	可创建	未声明
gemini.generate-content.text.v1beta	compatible	可创建	tools、tool_choice、parallel_tool_calls、text.format、user
bedrock.runtime.converse.text.v1	compatible	withheld（不可创建）	tools、tool_choice、parallel_tool_calls、text.format、user
bedrock.mantle.chat.v1	compatible	可创建	未声明
bedrock.mantle.openai.chat.v1	compatible	可创建	未声明
bedrock.mantle.responses.v1	compatible	可创建	tools
bedrock.mantle.openai.responses.v1	compatible	可创建	tools
bedrock.mantle.anthropic.messages.v1	compatible	可创建	text.format、user、input[].content[].detail
minimax.anthropic.messages.v1	compatible	可创建	text.format、user、input[].content[].detail
minimax.chat.v1	compatible	可创建	parallel_tool_calls、text.format、user
minimax.responses.v1	compatible	可创建	parallel_tool_calls、text.format、user
kimi.chat.v1	compatible	可创建	temperature、top_p、parallel_tool_calls、user、tool_choice
kimi.anthropic.messages.v1	compatible	可创建	temperature、top_p、text.format、user、input[].content[].detail
kimi.responses.v1	compatible	withheld（不可创建）	temperature、top_p、parallel_tool_calls、user
kimi.code.openai.chat.v1	experimental	可创建	parallel_tool_calls、temperature、text.format、tool_choice、top_p、user
minimax.cn.subscription.anthropic.messages.v1	experimental	withheld（不可创建）	input[].content[].detail、temperature、text.format、top_p、user
minimax.global.subscription.anthropic.messages.v1	experimental	withheld（不可创建）	input[].content[].detail、temperature、text.format、top_p、user
minimax.cn.subscription.openai.chat.v1	experimental	可创建	parallel_tool_calls、text.format、user
minimax.global.subscription.openai.chat.v1	experimental	可创建	parallel_tool_calls、text.format、user
kimi.code.anthropic.messages.v1	experimental	可创建	temperature、top_p、text.format、user、input[].content[].detail

已声明的变换

openai.chat-embeddings.v1

• 操作结论：Halro 会把 Responses items 转换到 the OpenAI Chat Completions ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the OpenAI Chat Completions ProviderPrimitive

openai.responses.v1

• 操作结论：该 Profile 只发送无状态 Responses，并强制上游 store=false；不要依赖 Provider 保存 Response。 原始契约：stateless Responses are sent directly with store=false
• 操作结论：使用 tools[].type=web_search 前，必须让所选连接显式声明 provider_executed_tools；否则该目标不可路由。 原始契约：tools[].type=web_search requires the selected connection to declare provider_executed_tools
• 操作结论：url_citation 注解会随输出文本返回；客户端应从注解字段读取并保留引用。 原始契约：url_citation annotations are carried back on the output text

anthropic.messages.2023-06-01

• 操作结论：Halro 会把 Responses items 转换到 the Anthropic Messages ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the Anthropic Messages ProviderPrimitive

anthropic.subscription.messages.v1

• 操作结论：Halro 会把 Responses items 转换到 the Anthropic Messages ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the Anthropic Messages ProviderPrimitive

azure-openai.chat-embeddings.v1

• 操作结论：Halro 会把 Responses items 转换到 the Azure Chat Completions ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the Azure Chat Completions ProviderPrimitive

deepseek.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the DeepSeek Chat ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the DeepSeek Chat ProviderPrimitive
• 操作结论：max_output_tokens 会映射为 DeepSeek max_tokens；此端点拒绝 reasoning，因此它只限制非推理输出。 原始契约：max_output_tokens is carried as DeepSeek’s max_tokens: it is a completion budget that counts reasoning, and this endpoint rejects the reasoning request field outright, so nothing served here thinks and the two bound the same tokens
• 操作结论：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
• 操作结论：DeepSeek 只支持无 schema 的 json_object；带 JSON Schema 的 text.format 会在 Provider I/O 前拒绝。 原始契约：text.format is value-dependent: DeepSeek has json_object and no schema mode, so a schema is rejected before provider I/O
• 操作结论：北向 user 会映射为 DeepSeek user_id；可用于该 Provider 支持的用户归因，但不要放入敏感身份信息。 原始契约：user is carried as DeepSeek’s user_id

bigmodel.cn.chat-embeddings.v1

• 操作结论：Halro 会把 Responses items 转换到 BigModel Chat Completions；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through BigModel Chat Completions
• 操作结论：max_output_tokens 会映射为 BigModel 的 max_tokens。 原始契约：max_output_tokens is carried as BigModel max_tokens
• 操作结论：function tools 按文档最多传递 128 个；不要超过该上限。 原始契约：function tools are carried up to the documented limit of 128
• 操作结论：依值决定的采样、user_id、图片 detail 和 tool choice 约束在 Provider I/O 前检查并拒绝不支持值。 原始契约：value-dependent sampling, user_id, image detail and tool choice constraints are rejected before provider I/O

bigmodel.cn.coding.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the Coding Plan’s Chat Completions route；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the Coding Plan’s Chat Completions route
• 操作结论：max_output_tokens 会映射为 BigModel 的 max_tokens。 原始契约：max_output_tokens is carried as BigModel max_tokens
• 操作结论：function tools 按文档最多传递 128 个；不要超过该上限。 原始契约：function tools are carried up to the documented limit of 128
• 操作结论：依值决定的采样、user_id、图片 detail 和 tool choice 约束在 Provider I/O 前检查并拒绝不支持值。 原始契约：value-dependent sampling, user_id, image detail and tool choice constraints are rejected before provider I/O

bigmodel.global.coding.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the international Coding Plan’s documented Chat Completions route；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the international Coding Plan’s documented Chat Completions route
• 操作结论：max_output_tokens 会映射为 BigModel 的 max_tokens。 原始契约：max_output_tokens is carried as BigModel max_tokens
• 操作结论：function tools 按文档最多传递 128 个；不要超过该上限。 原始契约：function tools are carried up to the documented limit of 128
• 操作结论：依值决定的采样、user_id、图片 detail 和 tool choice 约束在 Provider I/O 前检查并拒绝不支持值。 原始契约：value-dependent sampling, user_id, image detail and tool choice constraints are rejected before provider I/O

bigmodel.global.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 Z.AI Chat Completions；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through Z.AI Chat Completions
• 操作结论：max_output_tokens 会映射为 BigModel 的 max_tokens。 原始契约：max_output_tokens is carried as BigModel max_tokens
• 操作结论：function tools 按文档最多传递 128 个；不要超过该上限。 原始契约：function tools are carried up to the documented limit of 128
• 操作结论：依值决定的采样、user_id、图片 detail 和 tool choice 约束在 Provider I/O 前检查并拒绝不支持值。 原始契约：value-dependent sampling, user_id, image detail and tool choice constraints are rejected before provider I/O

openai-compatible.chat-embeddings.v1

• 操作结论：Halro 会把 Responses items 转换到 the compatible Chat Completions ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the compatible Chat Completions ProviderPrimitive

gemini.generate-content.text.v1beta

• 操作结论：Halro 会把 instructions 转换到 a developer message and merged into Gemini system_instruction；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：instructions are mapped to a developer message and merged into Gemini system_instruction

bedrock.runtime.converse.text.v1

• 操作结论：Halro 会把 instructions 转换到 a developer message；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：instructions are mapped to a developer message
• 操作结论：Halro 把 Bedrock stop reason 归一化为 Responses status；客户端不要依赖 Bedrock 原始枚举。 原始契约：Bedrock stop reasons are normalized to Responses status

bedrock.mantle.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 Bedrock Mantle Chat Completions；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through Bedrock Mantle Chat Completions

bedrock.mantle.openai.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 Bedrock Mantle Chat Completions；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through Bedrock Mantle Chat Completions

bedrock.mantle.responses.v1

• 操作结论：该 Profile 只发送无状态 Responses，并强制上游 store=false；不要依赖 Provider 保存 Response。 原始契约：stateless Responses are sent directly with store=false

bedrock.mantle.openai.responses.v1

• 操作结论：该 Profile 只发送无状态 Responses，并强制上游 store=false；不要依赖 Provider 保存 Response。 原始契约：stateless Responses are sent directly with store=false

bedrock.mantle.anthropic.messages.v1

• 操作结论：经 Anthropic 形状传图时，detail 只能省略或设为 auto；其他值会在 Provider I/O 前拒绝，不会静默丢弃。 原始契约：an Anthropic image source is base64, url, or file and has no member for the OpenAI fidelity hint, so detail is rejected before provider I/O at any value other than auto rather than dropped from a request that paid for it
• 操作结论：Halro 会把 Responses items 转换到 Bedrock Mantle Anthropic Messages；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through Bedrock Mantle Anthropic Messages

minimax.anthropic.messages.v1

• 操作结论：Halro 会把 Responses items 转换到 MiniMax’s Anthropic Messages ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through MiniMax’s Anthropic Messages ProviderPrimitive
• 操作结论：经 Anthropic 形状传图时，detail 只能省略或设为 auto；其他值会在 Provider I/O 前拒绝，不会静默丢弃。 原始契约：an Anthropic image source is base64, url, or file and has no member for the OpenAI fidelity hint, so detail is rejected before provider I/O at any value other than auto rather than dropped from a request that paid for it

minimax.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the MiniMax Chat ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the MiniMax Chat ProviderPrimitive
• 操作结论：max_output_tokens 会映射为 MiniMax max_completion_tokens；此端点拒绝 reasoning，因此两者语义一致。 原始契约：max_output_tokens is carried as MiniMax’s max_completion_tokens, which is the same quantity: this endpoint rejects the reasoning request field outright, so nothing served here thinks
• 操作结论：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means

minimax.responses.v1

• 操作结论：该 Profile 只发送无状态 Responses，并强制上游 store=false；不要依赖 Provider 保存 Response。 原始契约：stateless Responses are sent directly with store=false
• 操作结论：该 Responses Profile 无法无损返回 reasoning item；请求中必须省略 reasoning，需要推理时改用支持它的 Chat Profile。 原始契约：reasoning is rejected before provider I/O because the canonical response mapper cannot preserve the reasoning items MiniMax returns

kimi.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the Kimi Chat ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the Kimi Chat ProviderPrimitive
• 操作结论：Kimi 与 reasoning 同用时不要指定命名工具；required 仅在 kimi-k3 可与 depth 同用，K2.x 会在预留后拒绝，生产 Route 应按模型能力拆分。 原始契约：tool_choice is value-dependent: a named function together with a reasoning depth is refused by every Kimi model and is routed away before provider I/O
• 操作结论：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：Kimi does not model temperature or top_p as request members and pins each to one value per model, so they are rejected before provider I/O rather than sent or silently replaced
• 操作结论：max_output_tokens 会映射为 Kimi max_completion_tokens；按同一总输出上限处理。 原始契约：max_output_tokens is carried as Kimi’s max_completion_tokens, which Kimi documents as the same bound
• 操作结论：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means
• 操作结论：text.format 只用于带 schema 的 json_schema；不要提交无 schema 的 json_object。 原始契约：text.format is carried: the Kimi Chat face documents the json_schema response format alongside json_object

kimi.anthropic.messages.v1

• 操作结论：Halro 会把 Responses items 转换到 Kimi’s Anthropic Messages ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through Kimi’s Anthropic Messages ProviderPrimitive
• 操作结论：经 Anthropic 形状传图时，detail 只能省略或设为 auto；其他值会在 Provider I/O 前拒绝，不会静默丢弃。 原始契约：an Anthropic image source is base64, url, or file and has no member for the OpenAI fidelity hint, so detail is rejected before provider I/O at any value other than auto rather than dropped from a request that paid for it
• 操作结论：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：temperature and top_p are rejected because Kimi pins each per model
• 操作结论：该 Kimi Profile 只接受带 schema 的 text.format；无 schema 的 json_object 会被排除。 原始契约：text.format is value-dependent: this face takes a schema through output_config.format and enforces it, so a schema-less request is routed away

kimi.responses.v1

• 操作结论：该 Profile 只处理无状态 Responses，并直接调用 Provider；不要依赖 Provider 侧会话或存储。 原始契约：stateless Responses are sent directly
• 操作结论：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：Kimi does not model temperature or top_p as request members on this face either
• 操作结论：该 Responses Profile 无法无损返回 reasoning item；请求中必须省略 reasoning，需要推理时改用支持它的 Chat Profile。 原始契约：reasoning is rejected before provider I/O because the canonical response mapper cannot preserve the reasoning items Kimi returns
• 操作结论：text.format 只用于带 schema 的 json_schema；不要提交无 schema 的 json_object。 原始契约：text.format carries a schema; the schema-less json_object mode is routed away by the absent json_object capability rather than by field, because Kimi’s Responses face accepts the json_schema type alone
• 操作结论：此端点仅服务 kimi-k3；模型目录按单个模型记录支持范围。 原始契约：this endpoint serves kimi-k3 alone, which the model catalog records per model

kimi.code.openai.chat.v1

• 操作结论：Halro 会把 Responses items 转换到 the OpenAI Chat Completions ProviderPrimitive；调用方继续使用北向字段，并按目标 Profile 的字段矩阵核对转换损失。 原始契约：Responses items are mapped through the OpenAI Chat Completions ProviderPrimitive
• 操作结论：Kimi Code 的 OpenAI 兼容面使用专用请求渲染器；协议形状相同不表示接受全部 OpenAI 成员。 原始契约：Kimi Code’s OpenAI-compatible face is rendered by its own request renderer, not the OpenAI one: the shared wire shape does not extend to the accepted member list
• 操作结论：未请求 reasoning depth 时明确关闭 reasoning；此产品默认推理并计费，不能依赖上游默认值。 原始契约：reasoning is switched off explicitly on every request that asks for no depth, because each model this product serves reasons by default and bills for it
• 操作结论：输出总上限包含 reasoning；只有未开启 thinking 时，才能把 max_tokens 当作纯回答上限传递。 原始契约：the single output bound counts reasoning, so an answer-only max_tokens is carried only while nothing is thinking
• 操作结论：只接受此面发布的 low/high/max 深度；上游不强制这些档位，不能假定保留深度，未发布值会被拒绝。 原始契约：the published depth ladder is low/high/max and the upstream enforces none of it, so a depth this face does not publish is refused rather than served as the product’s default depth

minimax.cn.subscription.anthropic.messages.v1

• 操作结论：MiniMax Subscription Access 在独立产品面复用 Messages 渲染器；按量账号的 fixture 不作为订阅证据。 原始契约：MiniMax Subscription Access reuses the Anthropic Messages wire renderer on its isolated product surface; no metered-account fixture is credited to this profile
• 操作结论：Halro 会把便携请求转换到原始契约指明的 Provider primitive；只使用字段矩阵能保留的语义，需原样传递时改用原生模式。 原始契约：portable optional fields remain fail-closed until a subscription-key fixture establishes their behavior

minimax.global.subscription.anthropic.messages.v1

• 操作结论：MiniMax Subscription Access 在独立产品面复用 Messages 渲染器；按量账号的 fixture 不作为订阅证据。 原始契约：MiniMax Subscription Access reuses the Anthropic Messages wire renderer on its isolated product surface; no metered-account fixture is credited to this profile
• 操作结论：Halro 会把便携请求转换到原始契约指明的 Provider primitive；只使用字段矩阵能保留的语义，需原样传递时改用原生模式。 原始契约：portable optional fields remain fail-closed until a subscription-key fixture establishes their behavior

minimax.cn.subscription.openai.chat.v1

• 操作结论：MiniMax Subscription Access 在独立产品面复用 Chat 渲染器；按量账号的 fixture 不作为订阅证据。 原始契约：MiniMax Subscription Access reuses the OpenAI Chat wire renderer on its isolated product surface; no metered-account fixture is credited to this profile
• 操作结论：依值决定的可选字段在订阅密钥 fixture 建立证据前保持失败关闭，不能按协议相同推定支持。 原始契约：value-dependent optional fields remain fail-closed until a subscription-key fixture establishes their behavior

minimax.global.subscription.openai.chat.v1

• 操作结论：MiniMax Subscription Access 在独立产品面复用 Chat 渲染器；按量账号的 fixture 不作为订阅证据。 原始契约：MiniMax Subscription Access reuses the OpenAI Chat wire renderer on its isolated product surface; no metered-account fixture is credited to this profile
• 操作结论：依值决定的可选字段在订阅密钥 fixture 建立证据前保持失败关闭，不能按协议相同推定支持。 原始契约：value-dependent optional fields remain fail-closed until a subscription-key fixture establishes their behavior

kimi.code.anthropic.messages.v1

• 操作结论：Kimi Code 在独立会员接入面复用 Messages 渲染器；Kimi 开放平台 fixture 不作为会员产品证据。 原始契约：Kimi Code reuses the Anthropic Messages wire renderer on its isolated membership surface; no Kimi Open Platform fixture is credited to this profile
• 操作结论：可移植请求未指定深度时发送 thinking disabled；已在 k3、k3-256k、kimi-for-coding 的流式和非流式请求实测。 原始契约：thinking disabled is sent on every portable request that asks for no depth, and was measured honoured on k3, k3-256k and kimi-for-coding, non-streaming and streaming alike
• 操作结论：此面接受 temperature、top_k 并返回 200 却不能证明生效，因此 Halro 拒绝这些字段。 原始契约：temperature and top_k are refused here because this face accepts them and answers 200 without establishing that either was read, where the Chat face refuses them outright
• 操作结论：stop_sequences 已实测执行，但截断结果返回 stop_reason=end_turn 和空 stop_sequence，不要依赖命中的序列名。 原始契约：stop_sequences is carried and was measured honoured, but a cut answer reports stop_reason end_turn with a null stop_sequence rather than naming the sequence

证据

已验证的证据：gateway_contract、provider_transport_fixture、sdk_blackbox

SDK 黑盒协议桩矩阵

openai-go、openai-node、openai-python

警告

该矩阵只证明这些 SDK 版本能序列化请求、并消费 Halro 声明的响应与流形状。它跑的是协议桩， 不经过真实 Runtime 路由、Gateway Key 认证、路由选择、能力过滤、脱敏与预算核算， 不能被引为端到端网关或真实 Provider 的证据。

最佳实践

延迟任务见案例六，流式失败处理见案例七。

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 08af8c8b0b10 的兼容性契约生成 （scripts/generate-api-pages.mjs，当前副本摘要 db249a88ce62e5b7…）。

字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。

Footnotes

1. model 的组合级限制：

   • kimi.chat.v1：Kimi 与 reasoning 同用时不要指定命名工具；required 仅在 kimi-k3 可与 depth 同用，K2.x 会在预留后拒绝，生产 Route 应按模型能力拆分。 原始契约：tool_choice is value-dependent: a named function together with a reasoning depth is refused by every Kimi model and is routed away before provider I/O
   • kimi.chat.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：Kimi does not model temperature or top_p as request members and pins each to one value per model, so they are rejected before provider I/O rather than sent or silently replaced
   • kimi.anthropic.messages.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：temperature and top_p are rejected because Kimi pins each per model
   ↩

2. reasoning 的组合级限制：

   • minimax.responses.v1：该 Responses Profile 无法无损返回 reasoning item；请求中必须省略 reasoning，需要推理时改用支持它的 Chat Profile。 原始契约：reasoning is rejected before provider I/O because the canonical response mapper cannot preserve the reasoning items MiniMax returns
   • kimi.chat.v1：Kimi 与 reasoning 同用时不要指定命名工具；required 仅在 kimi-k3 可与 depth 同用，K2.x 会在预留后拒绝，生产 Route 应按模型能力拆分。 原始契约：tool_choice is value-dependent: a named function together with a reasoning depth is refused by every Kimi model and is routed away before provider I/O
   • kimi.responses.v1：该 Responses Profile 无法无损返回 reasoning item；请求中必须省略 reasoning，需要推理时改用支持它的 Chat Profile。 原始契约：reasoning is rejected before provider I/O because the canonical response mapper cannot preserve the reasoning items Kimi returns
   ↩

3. temperature 的组合级限制：

   • kimi.chat.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：Kimi does not model temperature or top_p as request members and pins each to one value per model, so they are rejected before provider I/O rather than sent or silently replaced
   • kimi.anthropic.messages.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：temperature and top_p are rejected because Kimi pins each per model
   • kimi.code.anthropic.messages.v1：此面接受 temperature、top_k 并返回 200 却不能证明生效，因此 Halro 拒绝这些字段。 原始契约：temperature and top_k are refused here because this face accepts them and answers 200 without establishing that either was read, where the Chat face refuses them outright
   ↩

4. top_p 的组合级限制：

   • kimi.chat.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：Kimi does not model temperature or top_p as request members and pins each to one value per model, so they are rejected before provider I/O rather than sent or silently replaced
   • kimi.anthropic.messages.v1：Kimi 对 temperature 和 top_p 使用模型固定值；请求中必须省略这两个字段，否则该 Profile 不可用。 原始契约：temperature and top_p are rejected because Kimi pins each per model
   ↩

5. tools 的组合级限制：

   • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
   ↩

6. tools[].type 的组合级限制：

   • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
   ↩

7. tools[].name 的组合级限制：

   • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
   ↩

8. tools[].description 的组合级限制：

   • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
   ↩

9. tools[].parameters 的组合级限制：

   • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
   ↩

10. tools[].strict 的组合级限制：

    • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
    ↩

11. tool_choice 的组合级限制：

    • kimi.chat.v1：Kimi 与 reasoning 同用时不要指定命名工具；required 仅在 kimi-k3 可与 depth 同用，K2.x 会在预留后拒绝，生产 Route 应按模型能力拆分。 原始契约：tool_choice is value-dependent: a named function together with a reasoning depth is refused by every Kimi model and is routed away before provider I/O
    ↩

12. parallel_tool_calls 的组合级限制：

    • deepseek.chat.v1：parallel_tool_calls 省略或设为 true 可用；设为 false（要求串行工具调用）时该 Profile 不可用。 原始契约：parallel_tool_calls is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
    ↩

13. text.format 的组合级限制：

    • deepseek.chat.v1：DeepSeek 只支持无 schema 的 json_object；带 JSON Schema 的 text.format 会在 Provider I/O 前拒绝。 原始契约：text.format is value-dependent: DeepSeek has json_object and no schema mode, so a schema is rejected before provider I/O
    • kimi.anthropic.messages.v1：该 Kimi Profile 只接受带 schema 的 text.format；无 schema 的 json_object 会被排除。 原始契约：text.format is value-dependent: this face takes a schema through output_config.format and enforces it, so a schema-less request is routed away
    • kimi.responses.v1：text.format 只用于带 schema 的 json_schema；不要提交无 schema 的 json_object。 原始契约：text.format carries a schema; the schema-less json_object mode is routed away by the absent json_object capability rather than by field, because Kimi’s Responses face accepts the json_schema type alone
    ↩