Chat Completions

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

状态语义：stateless

已声明的偏差

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

• gateway routes model names; provider-owned chat state is not exposed
• unknown request fields are rejected before provider I/O
• provider-specific unsupported fields are rejected before provider I/O

请求示例

curl

curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "chat", "max_tokens": 256,
        "messages": [{"role": "user", "content": "你好"}] }'

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)
response = client.chat.completions.create(
    model="chat", max_tokens=256,
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

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,
});
const response = await client.chat.completions.create({
  model: "chat", max_tokens: 256,
  messages: [{ role: "user", content: "你好" }],
});
console.log(response.choices[0].message.content);

SDK 默认会自动重试

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

请求头

• Authorization
• Content-Type

请求字段

怎么读这张表

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

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
messages	—	—
messages[].name	anthropic.messages.2023-06-01、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	—
stream	—	1 见脚注 1
stream_options	—	—
temperature	—	—
top_p	—	—
max_tokens	—	2 见脚注 2
max_completion_tokens	deepseek.chat.v1	3 见脚注 3
n	anthropic.messages.2023-06-01、deepseek.chat.v1、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.responses.v1、bedrock.mantle.anthropic.messages.v1	4 见脚注 4
stop	bedrock.mantle.openai.responses.v1	—
seed	anthropic.messages.2023-06-01、deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.responses.v1、bedrock.mantle.anthropic.messages.v1	—
tools	gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	5 见脚注 5
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	6 见脚注 6
response_format	anthropic.messages.2023-06-01、deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	7 见脚注 7
reasoning_effort	anthropic.messages.2023-06-01、deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.responses.v1、bedrock.mantle.anthropic.messages.v1	8 见脚注 8
user	anthropic.messages.2023-06-01、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	—

响应字段

id object created model choices usage

流事件

chat.completion.chunk [DONE] error

可路由的 Provider Profile 及各自成熟度

端点成熟度不提升单个 Profile

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

Provider Profile	成熟度	不支持的请求字段
openai.chat-embeddings.v1	compatible	未声明
anthropic.messages.2023-06-01	compatible	messages[].name、n、seed、response_format、reasoning_effort、user
azure-openai.chat-embeddings.v1	compatible	未声明
deepseek.chat.v1	compatible	n、seed、max_completion_tokens、parallel_tool_calls、response_format、reasoning_effort
openai-compatible.chat-embeddings.v1	compatible	未声明
gemini.generate-content.text.v1beta	compatible	messages[].name、seed、tools、tool_choice、parallel_tool_calls、response_format、reasoning_effort、user
bedrock.runtime.converse.text.v1	compatible	messages[].name、n、seed、tools、tool_choice、parallel_tool_calls、response_format、reasoning_effort、user
bedrock.mantle.openai.chat.v1	compatible	未声明
bedrock.mantle.openai.responses.v1	compatible	n、stop、seed、reasoning_effort
bedrock.mantle.anthropic.messages.v1	compatible	messages[].name、n、seed、response_format、reasoning_effort、user

已声明的变换

anthropic.messages.2023-06-01

• portable Chat content is mapped to Anthropic Messages blocks
• response_format and reasoning_effort are declared unsupported at field granularity because support is value-dependent: json_schema maps to output_config.format and the low/medium/high/xhigh/max ladder maps to output_config.effort, while json_object and any effort outside that ladder have no Anthropic representation and are routed away before provider I/O

deepseek.chat.v1

• DeepSeek speaks this wire format but accepts a smaller member list, so the fields it has no place for are rejected before provider I/O rather than sent and ignored
• user is carried as DeepSeek’s user_id
• reasoning_effort and response_format are declared unsupported at field granularity because support is value-dependent: none maps to thinking.type=disabled and the low and high rungs map to thinking.reasoning_effort with thinking enabled, while minimal, medium and xhigh have no DeepSeek rung; json_object maps to response_format and json_schema has no DeepSeek counterpart
• max_completion_tokens is value-dependent too: it counts reasoning tokens and DeepSeek’s max_tokens does not, so it is carried as max_tokens on a request with thinking off and rejected before provider I/O on one with thinking on, or on one that already carries max_tokens
• n and parallel_tool_calls are value-dependent in the same way: n=1 and parallel_tool_calls=true are what omitting the member already means, and only n>1 and a request to run tools one at a time are rejected

gemini.generate-content.text.v1beta

• developer messages are merged into Gemini system_instruction

bedrock.runtime.converse.text.v1

• Bedrock stop reasons are normalized to OpenAI finish reasons

bedrock.mantle.openai.responses.v1

• Chat messages are mapped to stateless Responses input items
• store=false is always sent upstream
• streaming requests with tools are rejected before provider I/O

bedrock.mantle.anthropic.messages.v1

• portable Chat content is mapped to Bedrock Mantle Anthropic Messages blocks

证据

已验证的证据：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. stream —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

2. max_tokens —— deepseek.chat.v1：max_completion_tokens is value-dependent too: it counts reasoning tokens and DeepSeek’s max_tokens does not, so it is carried as max_tokens on a request with thinking off and rejected before provider I/O on one with thinking on, or on one that already carries max_tokens ↩

3. max_completion_tokens —— deepseek.chat.v1：max_completion_tokens is value-dependent too: it counts reasoning tokens and DeepSeek’s max_tokens does not, so it is carried as max_tokens on a request with thinking off and rejected before provider I/O on one with thinking on, or on one that already carries max_tokens ↩

4. n —— deepseek.chat.v1：n and parallel_tool_calls are value-dependent in the same way: n=1 and parallel_tool_calls=true are what omitting the member already means, and only n>1 and a request to run tools one at a time are rejected ↩

5. tools —— deepseek.chat.v1：n and parallel_tool_calls are value-dependent in the same way: n=1 and parallel_tool_calls=true are what omitting the member already means, and only n>1 and a request to run tools one at a time are rejected；bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

6. parallel_tool_calls —— deepseek.chat.v1：n and parallel_tool_calls are value-dependent in the same way: n=1 and parallel_tool_calls=true are what omitting the member already means, and only n>1 and a request to run tools one at a time are rejected ↩

7. response_format —— anthropic.messages.2023-06-01：response_format and reasoning_effort are declared unsupported at field granularity because support is value-dependent: json_schema maps to output_config.format and the low/medium/high/xhigh/max ladder maps to output_config.effort, while json_object and any effort outside that ladder have no Anthropic representation and are routed away before provider I/O ↩

8. reasoning_effort —— anthropic.messages.2023-06-01：response_format and reasoning_effort are declared unsupported at field granularity because support is value-dependent: json_schema maps to output_config.format and the low/medium/high/xhigh/max ladder maps to output_config.effort, while json_object and any effort outside that ladder have no Anthropic representation and are routed away before provider I/O ↩