> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipellm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses 格式转换器

> 用 OpenAI Responses API 格式调用 Claude、Gemini 和 Chat Completions 模型

## 概述

Responses 格式转换器让 OpenAI Responses 客户端（OpenAI SDK 的
`client.responses`、Codex CLI 以及其他基于 Responses 的工具）可以调用
**Anthropic**、**Gemini** 和 **Chat Completions** 模型。原生支持 Responses API
的模型在同一路由上原样透传。

<Warning>
  该路由是 Responses API 的**无状态、部分兼容**实现：支持文本、图片、函数调用、
  推理和流式输出，不提供服务端响应存储，也不提供 OpenAI 托管工具。迁移工作流之前
  请先阅读[不支持的功能](#不支持的功能)。
</Warning>

## 配置

### SDK 配置

将 Base URL 设置为：

```
https://api.pipellm.ai/responses/v1
```

### cURL / 直接调用

```
https://api.pipellm.ai/responses/v1/responses
```

## 使用示例

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"dark"}
    from openai import OpenAI

    client = OpenAI(
        api_key="your-pipellm-api-key",
        base_url="https://api.pipellm.ai/responses/v1"
    )

    response = client.responses.create(
        model="claude-sonnet-4-6",  # 或 "gemini-3-flash-preview"
        input="Hello, how are you?",
        store=False,
    )

    print(response.output_text)
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={"dark"}
    import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: "your-pipellm-api-key",
      baseURL: "https://api.pipellm.ai/responses/v1",
    });

    const response = await client.responses.create({
      model: "claude-sonnet-4-6", // 或 "gemini-3-flash-preview"
      input: "Hello, how are you?",
      store: false,
    });

    console.log(response.output_text);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl https://api.pipellm.ai/responses/v1/responses \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer your-pipellm-api-key" \
      -d '{
        "model": "claude-sonnet-4-6",
        "input": "Hello, how are you?",
        "store": false
      }'
    ```
  </Tab>
</Tabs>

## 无状态多轮对话

转换目标模型不保存任何服务端会话状态。请发送 `store: false`（或不传 `store`），
并由客户端自行携带历史：每一轮都把上一次响应的**完整** `response.output` 数组追加到
`input`，再追加新的输入项。

```python theme={"dark"}
tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the weather for a city",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

history = [{"role": "user", "content": "What is the weather in Paris?"}]

first = client.responses.create(
    model="gemini-3-flash-preview",
    input=history,
    tools=tools,
    store=False,
    include=["reasoning.encrypted_content"],
)

# 原样回放所有输出项：reasoning（含 encrypted_content）、函数调用和消息。
history += [item.model_dump(exclude_none=True) for item in first.output]

for item in first.output:
    if item.type == "function_call":
        history.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": '{"temperature_c": 18}',
        })

final = client.responses.create(
    model="gemini-3-flash-preview",
    input=history,
    tools=tools,
    store=False,
    include=["reasoning.encrypted_content"],
)
print(final.output_text)
```

回放规则：

* 不要过滤、重排或改写输出项。reasoning 项的 `summary` 可能为空，只用于携带
  `encrypted_content`；它必须保持在与其一同返回的函数调用之前。
* 每个 `function_call_output` 引用的 `call_id` 必须出现在同一请求的 `input` 中。
  同一历史中出现重复的 `call_id` 会返回 `400`。
* `encrypted_content` 是不透明的提供商状态（Anthropic thinking 签名或 Gemini
  thought signature），只对签发它的提供商有效。其他提供商签发的内容会被忽略，
  不会被回放。

## 思考与签名

| 目标 | `encrypted_content` 携带的内容 | 未回放时 |
| - | - | - |
| Anthropic | 每个 thinking 块的 `signature`，以及 redacted thinking 的不透明 `data` | 上游请求中不包含此前的 thinking，对话在没有它的情况下继续 |
| Gemini | 函数调用 part 与单个 thought part 的 `thoughtSignature` | Gemini 3 模型会以 `400` 拒绝该函数调用回合 |

Gemini 3 模型会校验当前回合内函数调用的 thought signature。这是模型的原生要求，
不是转换器规则，详见 Google 官方的
[Thought signatures](https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures)
文档。转换器负责把每个签名放在 reasoning 项中返回，并在你回放该项时把签名还原到
对应的函数调用 part 上。

<Warning>
  **已知限制：Gemini 3 签名与上游渠道切换。** PipeLLM 可能通过不同的上游渠道
  处理同一模型的连续请求，而该路由不提供渠道亲和性。我们使用官方 OpenAI SDK
  验证时，客户端正确回放了 `encrypted_content`，落在同一渠道的回放均成功，但有一次
  回放落到了另一渠道，被上游以 `400 Thought signature is not valid` 拒绝。
  此限制尚未解决：重试可能成功，但无法保证，请在 Gemini 3 工具循环中处理该错误。
</Warning>

### Gemini 思考等级

Gemini 3 目标的 `reasoning.effort` 接受 `low`、`medium`、`high`，并映射为 `thinkingLevel`；Gemini 2.5 则使用 `thinkingBudget`。此转换路径不开放原生模型可能具备的 `minimal` 等其他等级；所选等级仍须由目标模型支持。

## 支持的功能

| 功能 | 状态 |
| - | - |
| 文本与图片输入（`input_text`、使用 URL 或 data URL 的 `input_image`） | ✅ 支持 |
| `instructions`、`system` / `developer` 消息 | ✅ 支持 |
| 流式输出（Responses SSE 事件） | ✅ 支持 |
| 函数调用，包括流式参数增量 | ✅ 支持 |
| `reasoning.effort`、`reasoning.summary`、`include: ["reasoning.encrypted_content"]` | ✅ 支持 |
| `custom`、`shell` / `local_shell`、`apply_patch`、`namespace` 工具 | ⚠️ 映射为函数工具并在输出中还原；custom 工具的 grammar 仅作为描述传递，不做强约束 |
| 函数工具的 `strict` | ⚠️ 仅对 OpenAI 目标生效 |
| `usage` | ✅ `input_tokens` 含缓存 token，`output_tokens` 含推理 token |

流式响应保证恰好以一个终态事件结束：`response.completed`、
`response.incomplete`（达到输出上限或内容过滤）或 `response.failed`
（上游错误或流被截断）。

`prompt_cache_key`、`client_metadata` 和 `stream_options.include_obfuscation`
会被接受，但不产生效果。

## 不支持的功能

对于转换目标模型，任何无法在目标协议中表达的内容都会返回 `400`，不会被静默丢弃：

| 功能 | 行为 |
| - | - |
| `store: true`、`previous_response_id`、`conversation`、`background: true` | `400` |
| `GET` / `DELETE /responses/{id}` 等存储类接口 | `404` |
| 托管工具：`web_search`、`file_search`、`code_interpreter`、`mcp`、图像生成、computer use | `400` |
| 结构化输出（纯文本以外的 `text.format`）、`text.verbosity` | `400` |
| `input_file`、图片 `file_id`、`item_reference` | `400` |
| `truncation: "auto"`、非空 `metadata`、带 `allowed_tools` 的 `tool_choice` | `400` |
| 未知的顶层字段，以及工具或输入项上的未知字段 | `400` |
| Gemini 目标：`parallel_tool_calls: false`、`low` / `medium` / `high` 以外的 `reasoning.effort` | `400` |

如果需要在 OpenAI 模型上使用这些功能，请走原生
[`/v1/responses`](/zh/api-reference/openai/responses) 路由。

## Codex CLI

Codex CLI 可以通过自定义 provider 使用该路由：设置 `wire_api = "responses"` 并使用
上面的 Base URL。对转换目标模型请关闭托管网页搜索（`web_search = "disabled"`），
因为托管工具会被拒绝。

## 相关文档

<Columns cols={3}>
  <Card title="Converter 总览" icon="shuffle" href="/zh/converter/overview">
    所有 converter 路由
  </Card>

  <Card title="原生 Responses" icon="sparkles" href="/zh/api-reference/openai/responses">
    面向 OpenAI 兼容模型的 `/v1/responses`
  </Card>

  <Card title="路由与协议" icon="route" href="/zh/guides/routing-protocols">
    原生路由与 converter 路由的区别
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.