跳转到主要内容
POST
/
api
/
v1
/
responses
curl -X POST https://aireiter.com/api/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "input": "Write a one-sentence bedtime story about a unicorn.",
    "stream": true
  }'

{
  "id": "resp_AbCdEfGhIjKlMnOpQrSt0123",
  "object": "response",
  "created_at": 1742000000.123,
  "status": "completed",
  "model": "claude-sonnet-4-5-20250929",
  "task_id": "task_xyz123",
  "output": [
    {
      "id": "msg_AbCdEfGhIjKl0123",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The little unicorn tiptoed through the moonlit meadow, leaving a trail of shimmering stardust as she galloped home to her cozy cloud.",
          "annotations": []
        }
      ]
    }
  ],
  "output_text": "The little unicorn tiptoed through the moonlit meadow, leaving a trail of shimmering stardust as she galloped home to her cozy cloud.",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 35,
    "total_tokens": 55,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

​
认证

​
Authorization
string
必填
Bearer Token 认证。格式：Authorization: Bearer <api-key>获取 API Key：访问 API Key 管理页面 获取您的 API Key
​
x-api-key
string
替代认证方式，与 Authorization 二选一。格式：x-api-key: <api-key>

​
请求体参数

​
model
string
必填
要使用的模型名称。示例：claude-sonnet-4-5-20250929、gpt-4o。可通过 GET /api/v1/models 获取完整模型列表。
​
input
array
必填
输入内容列表输入数组，每个输入项包含 role 和 content 两个字段。支持多轮对话和多模态内容（文本+图像）。
​
instructions
string
系统提示词（System Prompt）。用于设定模型的行为准则、角色身份或上下文背景。等效于消息数组中 role: "system" 的消息。
​
stream
boolean
默认值:"true"
是否启用流式输出。
  • true（默认）：以 SSE 事件流方式逐 token 返回，适合实时展示
  • false：等待完整响应后一次性返回，适合批量处理
​
max_output_tokens
integer
生成回复的最大 token 数。超出限制时响应 status 为 "incomplete"，incomplete_details.reason 为 "max_output_tokens"。
​
temperature
number
采样温度，范围 0 ~ 2。值越高输出越随机，值越低输出越确定性。不建议同时修改 temperature 和 top_p。
​
top_p
number
核采样概率，范围 0 ~ 1。模型仅从累积概率达到 top_p 的 token 中采样。
​
tools
array
可供模型调用的工具列表。当前仅支持 type: "function" 类型，不支持 web_search、file_search、computer_use 等内置工具。
​
tool_choice
string | object
默认值:"auto"
工具调用策略：
  • "auto"：模型自动决定是否调用工具
  • "none"：禁止调用工具
  • "required"：强制调用至少一个工具
  • { "type": "function", "name": "function_name" }：强制调用指定工具
​
parallel_tool_calls
boolean
默认值:"true"
是否允许模型并行调用多个工具。仅在提供了 tools 时有效。
​
text
object
输出格式控制。
​
reasoning
object
推理模式配置（适用于支持推理的模型，如 gpt-5.2 及以上）。

​
响应字段

​
id
string
响应唯一标识符，格式：resp_ + 24位随机字符串
​
object
string
固定为 "response"
​
created_at
number
响应创建时间，Unix 时间戳（秒，含毫秒精度）
​
status
string
响应状态：
  • "completed"：正常完成
  • "incomplete"：因 max_output_tokens 提前截止
  • "in_progress"：流式输出进行中（仅在流式事件中出现）
  • "failed"：生成失败
​
model
string
实际使用的模型名称
​
task_id
string
平台扩展字段。本次调用的计费任务 ID，可用于对账与消耗查询。注意：
  • 非流式：task_id 直接位于响应 JSON 的顶层
  • 流式：task_id 嵌套在 response.created（第一个事件）和 response.completed（最后一个事件）的 response 对象内，需解析原始 SSE 事件获取，OpenAI SDK 的流式接口不会自动暴露此字段
​
output
array
输出内容数组，可包含文本消息和工具调用两种类型。
​
output_text
string
快捷字段，等同于 output[0].content[0].text（纯文本场景）。工具调用场景下为空字符串。
​
usage
object
Token 用量统计。
​
incomplete_details
object | null
当 status 为 "incomplete" 时不为 null。
curl -X POST https://aireiter.com/api/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "input": "Write a one-sentence bedtime story about a unicorn.",
    "stream": true
  }'

{
  "id": "resp_AbCdEfGhIjKlMnOpQrSt0123",
  "object": "response",
  "created_at": 1742000000.123,
  "status": "completed",
  "model": "claude-sonnet-4-5-20250929",
  "task_id": "task_xyz123",
  "output": [
    {
      "id": "msg_AbCdEfGhIjKl0123",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The little unicorn tiptoed through the moonlit meadow, leaving a trail of shimmering stardust as she galloped home to her cozy cloud.",
          "annotations": []
        }
      ]
    }
  ],
  "output_text": "The little unicorn tiptoed through the moonlit meadow, leaving a trail of shimmering stardust as she galloped home to her cozy cloud.",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 35,
    "total_tokens": 55,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

​
流式响应事件

当 stream: true 时，接口以 text/event-stream 格式返回 SSE 事件流。每个事件格式如下： 
event: <event_type>
data: <JSON_payload>
所有事件 payload 均包含 sequence_number 字段（从 0 递增），用于确保客户端按顺序处理事件。
获取 task_id：如需在流式模式下获取计费任务 ID，请监听第一个 response.created 事件并读取 event.response.task_id。

​
事件序列（文本响应）

序号事件类型说明
1response.created响应对象创建，status: "in_progress"
2response.in_progress响应开始生成
3response.output_item.added输出消息项目添加
4response.content_part.added文本内容块添加，text: ""
5response.output_text.delta(重复) 逐 token 文本增量
6response.output_text.done文本内容完成，含完整文本
7response.content_part.done内容块完成
8response.output_item.done消息项目完成
9response.completed响应完成，含完整响应对象和 usage

​
事件序列（工具调用）

序号事件类型说明
…response.output_item.added函数调用项目添加
…response.function_call_arguments.delta(重复) 函数参数增量
…response.function_call_arguments.done函数参数完成
…response.output_item.done函数调用项目完成
最后response.completed响应完成

​
事件示例

{
  "type": "response.created",
  "sequence_number": 0,
  "response": {
    "id": "resp_AbCdEfGhIjKlMnOpQrSt0123",
    "object": "response",
    "created_at": 1742000000.123,
    "status": "in_progress",
    "model": "claude-sonnet-4-5-20250929",
    "task_id": "task_xyz123",
    "output": [],
    "output_text": ""
  }
}

​
使用示例

​
基础文本对话

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://aireiter.com/api/v1"
)

response = client.responses.create(
    model="claude-sonnet-4-5-20250929",
    instructions="You are a helpful coding assistant.",
    input="How do I reverse a string in Python?",
)

print(response.output_text)

​
图像理解

response = client.responses.create(
    model="claude-sonnet-4-5-20250929",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text",  "text": "What's in this image?"},
                {"type": "input_image", "image_url": {"url": "https://example.com/photo.jpg"}},
            ],
        }
    ],
)

print(response.output_text)

​
工具调用

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"},
                "unit":     {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["location"],
        },
    }
]

response = client.responses.create(
    model="gpt-5.2",
    input="What's the weather like in Tokyo?",
    tools=tools,
    tool_choice="auto",
)

# 检查是否有工具调用
for item in response.output:
    if item.type == "function_call":
        print(f"Tool: {item.name}, Args: {item.arguments}")

​
结构化输出（JSON Schema）

import json

schema = {
    "type": "object",
    "properties": {
        "name":    {"type": "string"},
        "age":     {"type": "integer"},
        "hobbies": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["name", "age", "hobbies"],
    "additionalProperties": False,
}

response = client.responses.create(
    model="claude-sonnet-4-5-20250929",
    input="Extract info: Alice is 30 years old and loves hiking and cooking.",
    text={
        "format": {
            "type":   "json_schema",
            "name":   "person_info",
            "strict": True,
            "schema": schema,
        }
    },
)

data = json.loads(response.output_text)
print(data)  # {"name": "Alice", "age": 30, "hobbies": ["hiking", "cooking"]}

​
推理模式

response = client.responses.create(
    model="claude-3-7-sonnet-20250219",  # 支持推理的模型
    input="Solve: If x + y = 10 and x * y = 21, what are x and y?",
    reasoning={"effort": "high"},
)

print(response.output_text)

​
多轮对话

previous_response_id 当前不生效，需手动在 input 中拼接历史消息： 
# 第一轮
response1 = client.responses.create(
    model="claude-sonnet-4-5-20250929",
    input="My name is Bob.",
)

# 第二轮：手动拼接历史消息
response2 = client.responses.create(
    model="claude-sonnet-4-5-20250929",
    input=[
        {"role": "user",      "content": "My name is Bob."},
        {"role": "assistant", "content": response1.output_text},
        {"role": "user",      "content": "What's my name?"},
    ],
)

print(response2.output_text)  # "Your name is Bob."

​
注意事项

  1. 默认流式：stream 参数默认为 true。如需非流式响应，需显式传入 "stream": false。
  2. 积分不足：余额不足时返回 HTTP 402，请充值后重试。
  3. text.format 支持有限：当前底层供应商对结构化输出支持有限——json_object 模式下模型可能仍输出 Markdown 代码块而非纯 JSON；json_schema 模式下 Schema 约束可能不被遵守。如需结构化输出，建议在 instructions 或 input 中明确描述所需格式。
  4. 工具参数：parameters 字段必须是合法的 JSON Schema，required 数组决定哪些参数为必填项。

​
错误码说明

HTTP 状态码error.type说明
400invalid_request_error请求参数无效（缺少必填字段、JSON 解析失败等）
401authentication_errorAPI Key 无效或已过期
402invalid_request_error账户积分不足
404not_found_error指定模型不存在
502api_error上游 AI 服务商全部不可用
503api_error无可用供应商配置