Responses（无状态）

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

状态语义：stateless; omitted store is treated as false; stateful fields are rejected before provider I/O

已声明的偏差

逐条来自契约，不是补充说明：

• only POST create is available; retrieval, deletion, cancellation, input_items, Conversations, background mode, and webhooks are unavailable
• store defaults to false and store=true is rejected
• hosted tools, strict function tools, reasoning output, and streaming function calls are rejected
• 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、background 等）会在到达 Provider 之前被拒。照搬 OpenAI 的多轮 Responses 用法在这里跑不通 —— 会话状态请由你的应用保存， 每次把完整上下文放进 input。

请求示例

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

请求字段

怎么读这张表

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

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
input	—	—
input[].type	—	—
input[].role	—	—
input[].content	—	—
input[].call_id	—	—
input[].name	—	—
input[].arguments	—	—
input[].output	—	—
input[].content[].type	—	—
input[].content[].text	—	—
input[].content[].image_url	—	—
input[].content[].detail	—	—
instructions	—	—
stream	—	—
store	—	—
temperature	—	—
top_p	—	—
max_output_tokens	—	—
tools	gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	1 见脚注 1
tools[].type	—	2 见脚注 2
tools[].name	—	3 见脚注 3
tools[].description	—	4 见脚注 4
tools[].parameters	—	5 见脚注 5
tools[].strict	—	6 见脚注 6
tool_choice	gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	—
parallel_tool_calls	deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	7 见脚注 7
text.format	anthropic.messages.2023-06-01、deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	8 见脚注 8
text.format.type	—	—
text.format.name	—	—
text.format.description	—	—
text.format.schema	—	—
text.format.strict	—	—
user	anthropic.messages.2023-06-01、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	—

门面层直接拒绝的字段

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

• store=true
• previous_response_id
• conversation
• background
• 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 自己的覆盖记录。

Provider Profile	成熟度	不支持的请求字段
openai.chat-embeddings.v1	compatible	未声明
anthropic.messages.2023-06-01	compatible	text.format、user
azure-openai.chat-embeddings.v1	compatible	未声明
deepseek.chat.v1	compatible	parallel_tool_calls、text.format
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	tools、tool_choice、parallel_tool_calls、text.format、user
bedrock.mantle.openai.chat.v1	compatible	未声明
bedrock.mantle.openai.responses.v1	compatible	未声明
bedrock.mantle.anthropic.messages.v1	compatible	text.format、user

已声明的变换

openai.chat-embeddings.v1

• Responses items are mapped through the OpenAI Chat Completions ProviderPrimitive

anthropic.messages.2023-06-01

• Responses items are mapped through the Anthropic Messages ProviderPrimitive

azure-openai.chat-embeddings.v1

• Responses items are mapped through the Azure Chat Completions ProviderPrimitive

deepseek.chat.v1

• Responses items are mapped through the DeepSeek Chat ProviderPrimitive
• 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 is value-dependent: true is what omitting the member already means, and only a request to run tools one at a time is rejected
• text.format is value-dependent: DeepSeek has json_object and no schema mode, so a schema is rejected before provider I/O
• user is carried as DeepSeek’s user_id

openai-compatible.chat-embeddings.v1

• Responses items are mapped through the compatible Chat Completions ProviderPrimitive

gemini.generate-content.text.v1beta

• instructions are mapped to a developer message and merged into Gemini system_instruction

bedrock.runtime.converse.text.v1

• instructions are mapped to a developer message
• Bedrock stop reasons are normalized to Responses status

bedrock.mantle.openai.chat.v1

• Responses items are mapped through Bedrock Mantle Chat Completions

bedrock.mantle.openai.responses.v1

• stateless Responses are sent directly with store=false

bedrock.mantle.anthropic.messages.v1

• Responses items are mapped through Bedrock Mantle Anthropic Messages

证据

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

SDK 黑盒协议桩矩阵

openai-go、openai-node、openai-python

警告

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

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 7117fdc38491 的兼容性契约生成 （scripts/generate-api-pages.mjs，契约摘要 9f8a5c57f76ae870…）。 字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。

Footnotes

1. tools —— deepseek.chat.v1：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 ↩

2. tools[].type —— deepseek.chat.v1：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 ↩

3. tools[].name —— deepseek.chat.v1：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 ↩

4. tools[].description —— deepseek.chat.v1：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 ↩

5. tools[].parameters —— deepseek.chat.v1：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[].strict —— deepseek.chat.v1：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. parallel_tool_calls —— deepseek.chat.v1：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. text.format —— deepseek.chat.v1：text.format is value-dependent: DeepSeek has json_object and no schema mode, so a schema is rejected before provider I/O ↩