diff --git a/docs/analysis_reference/analysis_cc-switch.md b/docs/analysis_reference/analysis_cc-switch.md new file mode 100644 index 0000000..db331c4 --- /dev/null +++ b/docs/analysis_reference/analysis_cc-switch.md @@ -0,0 +1,722 @@ +# CC-Switch API 转换层详细分析报告 + +## 1. 项目概述 + +**CC-Switch** 是一个基于 **Tauri (Rust 后端 + Web 前端)** 的桌面应用，用于管理多个大模型编程工具（Claude Code、Codex CLI、Gemini CLI 等）的配置切换。其核心功能之一是**本地 HTTP 代理服务器**，在客户端与上游 LLM API 之间充当协议翻译层，使仅支持特定 API 格式的客户端（如 Claude Code 只支持 Anthropic Messages API）能通过代理访问不同协议的后端服务。 + +### 核心能力 + +- 将 **Anthropic Messages API** 请求/响应转换为 **OpenAI Chat Completions**、**OpenAI Responses API**、**Google Gemini Native** 等格式 +- 支持**流式 (SSE)** 和**非流式**两种模式的实时协议翻译 +- 内置故障转移、熔断器、Thinking 自修复、Copilot 请求优化等企业级特性 +- 支持 GitHub Copilot、ChatGPT Plus/Pro (Codex OAuth) 等动态 Token 认证的供应商 + +### 与同类项目的核心差异 + +CC-Switch 是唯一的**桌面端**代理工具（非服务端部署），面向个人开发者场景。其协议转换是**单方向锚定**的——以 Anthropic Messages API 为唯一"客户端协议"，向多种上游协议转换。相比 One-API / New-API 的多协议互转、LiteLLM 的 OpenAI-centric 统一格式，CC-Switch 的转换矩阵更聚焦但深度更大（如 Gemini Shadow Store、Copilot Optimizer 等属于独有的复杂机制）。 + +--- + +## 2. 技术架构总览 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CC-Switch Tauri 桌面应用 │ +├─────────────────────────────────────────────────────────────────┤ +│ Web 前端 (React) │ Rust 后端 (Tauri) │ +│ │ ┌──────────────────────────────────────┐ │ +│ - 供应商管理 │ │ proxy/ 模块 (Axum HTTP Server) │ │ +│ - 配置切换 │ │ │ │ +│ - 用量展示 │ │ ┌──────────┐ ┌────────────────┐ │ │ +│ │ │ │ server.rs│──▶│ handlers.rs │ │ │ +│ │ │ │ (路由层) │ │ (请求分发器) │ │ │ +│ │ │ └──────────┘ └───────┬────────┘ │ │ +│ │ │ │ │ │ +│ │ │ ┌──────────────────────▼─────────┐ │ │ +│ │ │ │ forwarder.rs (转发器) │ │ │ +│ │ │ │ - 供应商选择 / 故障转移 │ │ │ +│ │ │ │ - 请求体预处理 / 参数过滤 │ │ │ +│ │ │ │ - Thinking 自修复 / Copilot优化 │ │ │ +│ │ │ └──────────────┬─────────────────┘ │ │ +│ │ │ │ │ │ +│ │ │ ┌──────────────▼─────────────────┐ │ │ +│ │ │ │ providers/ (适配器层) │ │ │ +│ │ │ │ │ │ │ +│ │ │ │ ┌─────────┐ ┌──────────────┐ │ │ │ +│ │ │ │ │adapter.rs│ │ claude.rs │ │ │ │ +│ │ │ │ │(Trait定义)│ │ (Claude适配器)│ │ │ │ +│ │ │ │ └─────────┘ ├──────────────┤ │ │ │ +│ │ │ │ │ codex.rs │ │ │ │ +│ │ │ │ ├──────────────┤ │ │ │ +│ │ │ │ │ gemini.rs │ │ │ │ +│ │ │ │ └──────────────┘ │ │ │ +│ │ │ └─────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ │ ┌─────────────────────────────────┐ │ │ +│ │ │ │ 转换层 (transform/ 模块) │ │ │ +│ │ │ │ │ │ │ +│ │ │ │ transform.rs (→Chat) │ │ │ +│ │ │ │ transform_responses.rs (→Resp) │ │ │ +│ │ │ │ transform_gemini.rs (→Gemini)│ │ │ +│ │ │ └─────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ │ ┌─────────────────────────────────┐ │ │ +│ │ │ │ 流式转换层 (streaming/ 模块) │ │ │ +│ │ │ │ │ │ │ +│ │ │ │ streaming.rs (Chat) │ │ │ +│ │ │ │ streaming_responses.rs (Resp) │ │ │ +│ │ │ │ streaming_gemini.rs (Gemini) │ │ │ +│ │ │ └─────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ │ ┌─────────────────────────────────┐ │ │ +│ │ │ │ 辅助模块 │ │ │ +│ │ │ │ gemini_shadow.rs (状态回放) │ │ │ +│ │ │ │ gemini_schema.rs (Schema转换) │ │ │ +│ │ │ │ copilot_optimizer.rs (Copilot优化)│ │ │ +│ │ │ │ thinking_rectifier.rs (Thinking修复)│ │ +│ │ │ │ thinking_budget_rectifier.rs │ │ │ +│ │ │ │ cache_injector.rs (缓存注入) │ │ │ +│ │ │ │ body_filter.rs (私有参数过滤) │ │ │ +│ │ │ │ model_mapper.rs (模型名映射) │ │ │ +│ │ │ │ gemini_url.rs (Gemini URL构建)│ │ │ +│ │ │ └─────────────────────────────────┘ │ │ +│ │ └──────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**源文件规模**：`proxy/` 目录共 53 个源文件，其中核心转换层 6 个文件合计约 7,700 行，辅助模块 7 个文件合计约 4,000 行，转发器和处理器合计约 3,700 行。 + +--- + +## 3. 路由层 (server.rs) + +**文件**: `src-tauri/src/proxy/server.rs` (354 行) + +代理服务器基于 **Axum** 框架构建，使用手动 hyper HTTP/1.1 accept loop（通过 TCP `peek()` 捕获原始请求头大小写，存入 `OriginalHeaderCases` 扩展供转发器使用）。 + +### 路由表 + +| 路由路径 | 处理器 | 协议 | +|---------|--------|------| +| `/v1/messages`, `/claude/v1/messages` | `handle_messages` | Claude (Anthropic Messages API) | +| `/chat/completions`, `/v1/chat/completions`, `/v1/v1/chat/completions`, `/codex/v1/chat/completions` | `handle_chat_completions` | OpenAI Chat Completions | +| `/responses`, `/v1/responses`, `/v1/v1/responses`, `/codex/v1/responses` | `handle_responses` | OpenAI Responses API | +| `/responses/compact`, `/v1/responses/compact`, `/v1/v1/responses/compact`, `/codex/v1/responses/compact` | `handle_responses_compact` | Responses Compact (Codex CLI 远程压缩透传) | +| `/v1beta/*path`, `/gemini/v1beta/*path` | `handle_gemini` | Gemini (Google AI API) | +| `/health` | `health_check` | 健康检查 | +| `/status` | `get_status` | 状态查询 | + +**关键设计细节**: +- **多前缀兼容**: 裸路径 (`/v1/...`) 和带供应商前缀 (`/claude/`, `/codex/`, `/gemini/`) 均支持，兼容不同客户端的 `base_url` 配置 +- **双前缀容错**: `/v1/v1/...` 路由处理客户端双重前缀的配置错误 +- **无前缀路由**: `/chat/completions` 和 `/responses` 不带 `/v1/`，适配 Codex CLI 的特定 base_url 配置 +- **请求体限制**: `DefaultBodyLimit::max(200MB)`，支撑大体积上下文和图片请求 + +--- + +## 4. 适配器层 (Adapter Pattern) + +### 4.1 ProviderAdapter Trait + +**文件**: `src-tauri/src/proxy/providers/adapter.rs` (50 行) + +所有供应商适配器都实现统一的 `ProviderAdapter` trait： + +```rust +pub trait ProviderAdapter: Send + Sync { + fn name(&self) -> &'static str; + fn extract_base_url(&self, provider: &Provider) -> Result; + fn extract_auth(&self, provider: &Provider) -> Option; + fn build_url(&self, base_url: &str, endpoint: &str) -> String; + fn get_auth_headers(&self, auth: &AuthInfo) -> Vec<(HeaderName, HeaderValue)>; + fn needs_transform(&self, _provider: &Provider) -> bool; // 默认 false + fn transform_request(&self, body: Value, provider: &Provider) -> Result; // 默认透传 + fn transform_response(&self, body: Value) -> Result; // 默认透传 +} +``` + +其中 `needs_transform()`、`transform_request()`、`transform_response()` 提供默认实现（透传），供应商适配器仅需覆写需要的方法。 + +### 4.2 供应商类型枚举 (ProviderType) + +**文件**: `src-tauri/src/proxy/providers/mod.rs` (515 行) + +系统定义 8 种供应商类型，决定认证和请求处理逻辑： + +| ProviderType | 说明 | 认证策略 | 是否需要转换 | +|---|---|---|---| +| `Claude` | Anthropic 官方 API | Anthropic (`x-api-key`) | 视 api_format 决定 | +| `ClaudeAuth` | Claude 中转服务 (仅 Bearer) | ClaudeAuth | 视 api_format 决定 | +| `Codex` | OpenAI Codex | Bearer | 否 | +| `Gemini` | Google Gemini API (API Key) | Google (`x-goog-api-key`) | 否 | +| `GeminiCli` | Gemini CLI (OAuth) | GoogleOAuth | 否 | +| `OpenRouter` | OpenRouter 中转 | Bearer | 否 (已支持原生) | +| `GitHubCopilot` | GitHub Copilot | GitHubCopilot (动态 Token) | **是** → OpenAI Chat/Responses | +| `CodexOAuth` | ChatGPT Plus/Pro 反代 | CodexOAuth (动态 Token) | **是** → OpenAI Responses | + +**适配器工厂** `get_adapter_for_provider_type()` 的映射逻辑： +- `Claude`, `ClaudeAuth`, `OpenRouter`, `GitHubCopilot`, `CodexOAuth` → `ClaudeAdapter` +- `Codex` → `CodexAdapter` +- `Gemini`, `GeminiCli` → `GeminiAdapter` + +### 4.3 API 格式识别 + +**文件**: `src-tauri/src/proxy/providers/claude.rs` (1313 行) + +Claude 适配器通过 `get_claude_api_format()` 函数识别需要使用的 API 格式，优先级为： + +1. **Codex OAuth 强制**: `meta.provider_type == "codex_oauth"` → `openai_responses` +2. **meta.apiFormat (SSOT)**: `meta.api_format` 字段 → `openai_chat` / `openai_responses` / `gemini_native` +3. **settings_config.api_format**: 旧版兼容 +4. **openrouter_compat_mode**: 旧版 OpenRouter 兼容开关 → `openai_chat` +5. **默认**: `anthropic` (直接透传) + +### 4.4 认证策略 + +**文件**: `src-tauri/src/proxy/providers/auth.rs` (259 行) + +7 种认证策略覆盖所有上游服务： + +| 策略 | Header 注入 | +|------|-----------| +| `Anthropic` | `x-api-key: ` + `anthropic-version: 2023-06-01` (版本由转发器注入) | +| `ClaudeAuth` | `Authorization: Bearer ` (无 `x-api-key`) | +| `Bearer` | `Authorization: Bearer ` | +| `Google` | `x-goog-api-key: ` | +| `GoogleOAuth` | `Authorization: Bearer ` + `x-goog-client: GeminiCLI/1.0` | +| `GitHubCopilot` | `Authorization: Bearer ` + 多个 Copilot 专有 Header (`openai-intent`, `x-initiator`, `x-interaction-type`, `x-request-id`, `x-agent-task-id` 等约 10 个) | +| `CodexOAuth` | `Authorization: Bearer ` + `originator: cc-switch` + `chatgpt-account-id` | + +**动态认证机制**: GitHub Copilot 和 Codex OAuth 的 Token 是动态获取的，通过 `CopilotAuthManager` 和 `CodexOAuthAuth` 分别管理 Token 的刷新和多账户绑定（通过 `meta.authBinding` 实现供应商到账户的映射）。 + +--- + +## 5. 转换层详解 — 核心协议转换 + +### 5.1 Anthropic ↔ OpenAI Chat Completions + +**文件**: `src-tauri/src/proxy/providers/transform.rs` (1193 行) + +#### 请求转换: `anthropic_to_openai(body) → Value` + +将 Anthropic Messages API 请求转换为 OpenAI Chat Completions 请求。 + +**字段映射**: + +| Anthropic 字段 | OpenAI 字段 | 说明 | +|---|---|---| +| `system` (string) | `messages[0].role = "system"` | System prompt 提升为 system role message | +| `system` (array) | `messages[0].role = "system"` (合并) | 多个 system message 合并，冲突的 `cache_control` 被丢弃 | +| `messages` | `messages` | 按角色转换内容格式 | +| `max_tokens` | `max_tokens` / `max_completion_tokens` | o-series 模型使用 `max_completion_tokens` | +| `temperature` | `temperature` | 直接透传 | +| `top_p` | `top_p` | 直接透传 | +| `stop_sequences` | `stop` | 直接透传 | +| `tools[].input_schema` | `tools[].function.parameters` | Schema 格式转换，过滤 `BatchTool`，移除 `format: "uri"` | +| `tool_choice` | `tool_choice` | 直接透传 | +| `thinking` + `output_config.effort` | `reasoning_effort` | 仅对支持推理的模型注入 (o-series, GPT-5+) | + +**消息内容转换**: +- `text` → `{type: "text", text: "..."}` +- `image` → `{type: "image_url", image_url: {url: "data:...;base64,..."}}` (data URI) +- `tool_use` → `tool_calls[{id, type: "function", function: {name, arguments}}]` +- `tool_result` → `{role: "tool", tool_call_id: "...", content: "..."}` (独立 tool role 消息) +- `thinking` → 丢弃 + +**推理强度 (reasoning_effort) 映射规则**: + +| Anthropic thinking 配置 | OpenAI reasoning_effort | +|---|---| +| `type: "adaptive"` | `"xhigh"` | +| `type: "enabled"` + budget < 4000 | `"low"` | +| `type: "enabled"` + budget 4000-15999 | `"medium"` | +| `type: "enabled"` + budget >= 16000 | `"high"` | +| `type: "enabled"` + 无 budget | `"high"` | +| `output_config.effort: "max"` | `"xhigh"` | + +**特殊处理**: +- 多个 system message 自动合并，冲突的 `cache_control` 被丢弃 +- 支持 `cache_control` 在 system message、text block、tool 上的透传 +- `clean_schema()` 清理 JSON Schema 中 OpenAI 不支持的 `format: "uri"` 等字段 + +#### 响应转换: `openai_to_anthropic(body) → Value` + +| OpenAI 字段 | Anthropic 字段 | +|---|---| +| `choices[0].message.content` | `content[{type: "text"}]` | +| `choices[0].message.tool_calls` | `content[{type: "tool_use", id, name, input}]` | +| `choices[0].message.function_call` | `content[{type: "tool_use"}]` (旧格式兼容) | +| `choices[0].message.refusal` | `content[{type: "text", text: refusal}]` | +| `choices[0].finish_reason` | `stop_reason` (stop→end_turn, length→max_tokens, tool_calls→tool_use) | +| `usage.prompt_tokens` | `usage.input_tokens` | +| `usage.completion_tokens` | `usage.output_tokens` | +| `usage.prompt_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` | + +--- + +### 5.2 Anthropic ↔ OpenAI Responses API + +**文件**: `src-tauri/src/proxy/providers/transform_responses.rs` (1329 行) + +Responses API 是 OpenAI 2025 年推出的新一代 API，采用扁平化的 input/output 结构。 + +#### 请求转换: `anthropic_to_responses(body, cache_key, is_codex_oauth) → Value` + +| Anthropic 字段 | Responses API 字段 | 说明 | +|---|---|---| +| `system` | `instructions` | System prompt 转为 instructions 字段 | +| `messages` | `input` | 消息数组转为扁平化的 input items | +| `max_tokens` | `max_output_tokens` | 统一使用 max_output_tokens | +| `tools[].input_schema` | `tools[].parameters` | Schema 格式转换，移除 `cache_control` | +| `tool_choice.type = "any"` | `tool_choice = "required"` | 映射工具选择策略 | +| `tool_choice.type = "tool"` | `tool_choice = {type: "function", name}` | 强制指定工具 | +| `thinking` | `reasoning.effort` | 推理强度映射 | + +**消息结构转换核心差异** — 消息从"嵌套在 role message 中"变为"独立 top-level item"： +- `tool_use` 从 assistant message 中**提升**为独立的 `function_call` item: + ```json + // Anthropic + {"role": "assistant", "content": [{"type": "tool_use", "id": "call_1", ...}]} + // Responses API + {"type": "function_call", "call_id": "call_1", ...} + ``` +- `tool_result` 从 user message 中**提升**为独立的 `function_call_output` item: + ```json + // Anthropic + {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_1", ...}]} + // Responses API + {"type": "function_call_output", "call_id": "call_1", ...} + ``` +- 文本类型区分: user 的 text → `input_text`, assistant 的 text → `output_text` + +**Codex OAuth (ChatGPT Plus/Pro 反代) 特殊协议约束**: + +当 `is_codex_oauth = true` 时，需满足 ChatGPT 后端的协议限制： +- `store: false` — 不允许服务端持久化 +- `include: ["reasoning.encrypted_content"]` — 保持多轮 reasoning 上下文（ChatGPT 后端通过加密 reasoning blob 维持推理状态） +- 删除 `max_output_tokens`、`temperature`、`top_p` (ChatGPT 后端不支持这些参数) +- 兜底注入 `instructions`("")、`tools`([])、`parallel_tool_calls`(false) 默认值 +- 强制 `stream: true` (CC-Switch SSE 解析层只支持流式) + +#### 响应转换: `responses_to_anthropic(body) → Value` + +| Responses API 字段 | Anthropic 字段 | +|---|---| +| `output[type="message"].content[type="output_text"]` | `content[{type: "text"}]` | +| `output[type="function_call"]` | `content[{type: "tool_use", id: call_id, name, input}]` | +| `output[type="reasoning"].summary` | `content[{type: "thinking", thinking: ...}]` | +| `output[type="message"].content[type="refusal"]` | `content[{type: "text"}]` | +| `status = "completed"` (无 tool_use) | `stop_reason: "end_turn"` | +| `status = "completed"` (有 function_call) | `stop_reason: "tool_use"` | +| `status = "incomplete"` (reason: max_output_tokens) | `stop_reason: "max_tokens"` | +| `usage.input_tokens` | `usage.input_tokens` | +| `usage.input_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` | + +--- + +### 5.3 Anthropic ↔ Google Gemini Native + +**文件**: `src-tauri/src/proxy/providers/transform_gemini.rs` (2152 行) + +将 Anthropic Messages 请求转换为 Gemini `generateContent` 格式。这是三个转换中最复杂的，涉及有状态管理。 + +#### 请求转换: `anthropic_to_gemini_with_shadow(body, shadow_store, provider_id, session_id) → Value` + +| Anthropic 字段 | Gemini 字段 | 说明 | +|---|---|---| +| `system` | `systemInstruction.parts[{text}]` | System prompt 转为 systemInstruction | +| `messages` | `contents[{role, parts}]` | role: assistant→model, 其他→user | +| `max_tokens` | `generationConfig.maxOutputTokens` | | +| `temperature` | `generationConfig.temperature` | | +| `top_p` | `generationConfig.topP` | | +| `stop_sequences` | `generationConfig.stopSequences` | | +| `tools[].input_schema` | `tools[].functionDeclarations[]` | 转为 Gemini FunctionDeclaration | +| `tool_choice` | `toolConfig.functionCallingConfig` | auto→AUTO, none→NONE, any→ANY, tool→ANY+allowedFunctionNames | + +**消息内容转换**: +- `text` → `{text: "..."}` +- `image` (base64) → `{inlineData: {mimeType, data}}` +- `document` (base64) → `{inlineData: {mimeType, data}}` +- `tool_use` → `{functionCall: {name, args, id}}` (仅 assistant) +- `tool_result` → `{functionResponse: {name, response, id}}` (通过 id→name 映射解析) +- `thinking` / `redacted_thinking` → 丢弃 + +#### Shadow Store (状态回放机制) + +**文件**: `src-tauri/src/proxy/providers/gemini_shadow.rs` (389 行) + +Gemini 的 `thoughtSignature` 和 `functionCall.id` 是有状态的，需要跨轮次保留。CC-Switch 实现了 `GeminiShadowStore` 来解决此问题： + +- **存储结构**: 以 `(provider_id, session_id)` 为键，存储 `GeminiAssistantTurn`（包含 assistant_content + tool_calls 及 thoughtSignature） +- **容量限制**: 默认 200 个 session，每 session 64 轮对话，超出后 LRU 淘汰最旧 session +- **回放机制**: 在后续请求中，将存储的 shadow turn（包含 thoughtSignature 和原始 Gemini 格式内容）替换到对应 assistant 消息的位置，确保多轮对话的 `functionResponse` 和 `thoughtSignature` 能正确传递 +- **线程安全**: 使用 `std::sync::RwLock`（非 tokio async lock），因为 shadow store 操作很快 + +#### 工具参数修正 (Tool Call Rectification) + +Gemini 模型有时会将工具调用的参数结构"展平"或混淆（如将 `{skill: "git-commit"}` 发为 `{name: "git-commit"}`）。系统通过 `AnthropicToolSchemaHints` 机制： +1. 从请求中的 `tools[].input_schema` 提取预期参数结构 +2. 在响应中检测并修正参数名映射 (如 `name` → `skill`) +3. 处理 `parameters` 嵌套展平问题 +4. 通过 `rectify_tool_call_parts()` 实现类型强制转换（如 string `"123"` → integer `123`） + +#### 合成 ID 机制 + +Gemini 2.x 并行调用常省略 `functionCall.id`。系统处理： +- `synthesize_tool_call_id()` 生成 `gemini_synth_` 格式的合成 ID，在 Anthropic 侧使用 +- **不会**转发回 Gemini（在构建 Gemini 请求时被过滤） +- 流式场景支持 "synth → real id upgrade"：当后续 chunk 携带真实 ID 时替换合成 ID + +#### Gemini Schema 构建 + +**文件**: `src-tauri/src/proxy/providers/gemini_schema.rs` (338 行) + +工具定义的 Schema 转换使用双通道策略： +- **`parameters` 通道**: 使用受限的 Gemini Schema 格式（去掉 `$ref`, `$defs`, `additionalProperties`, `oneOf`, `allOf`, `const`, `not`, `if/then/else` 等不支持的关键字） +- **`parametersJsonSchema` 通道**: 使用完整 JSON Schema 格式（当 Schema 包含 Gemini 不支持的关键字时自动升级） +- `build_gemini_function_parameters()` 自动根据 Schema 复杂度选择通道 + +#### 响应转换: `gemini_to_anthropic_with_shadow_and_hints(body, ...) → Value` + +| Gemini 字段 | Anthropic 字段 | +|---|---| +| `candidates[0].content.parts[{text}]` | `content[{type: "text"}]` | +| `candidates[0].content.parts[{functionCall}]` | `content[{type: "tool_use", id, name, input}]` | +| `candidates[0].content.parts[{thought: true}]` | 丢弃 (Gemini thinking) | +| `candidates[0].finishReason = "STOP"` | `stop_reason: "end_turn"` / `"tool_use"` | +| `candidates[0].finishReason = "MAX_TOKENS"` | `stop_reason: "max_tokens"` | +| `candidates[0].finishReason = "SAFETY"` 等 | `stop_reason: "refusal"` | +| `promptFeedback.blockReason` | `stop_reason: "refusal"` + 错误文本 | +| `usageMetadata.promptTokenCount` | `usage.input_tokens` | +| `usageMetadata.cachedContentTokenCount` | `usage.cache_read_input_tokens` | + +--- + +## 6. 流式转换层 + +### 6.1 OpenAI Chat Completions SSE → Anthropic SSE + +**文件**: `src-tauri/src/proxy/providers/streaming.rs` (821 行) + +**转换状态机**: + +``` +OpenAI SSE chunk ──▶ 状态解析 ──▶ Anthropic SSE event + │ + choices[0].delta.content ──────▶ content_block_start (type: "text") + content_block_delta (type: "text_delta") + content_block_stop + + choices[0].delta.reasoning ────▶ content_block_start (type: "thinking") + content_block_delta (type: "thinking_delta") + content_block_stop + + choices[0].delta.tool_calls ───▶ content_block_start (type: "tool_use") + content_block_delta (type: "input_json_delta") + content_block_stop + + choices[0].finish_reason ──────▶ message_delta (stop_reason) + [DONE] ───────────────────────▶ message_stop +``` + +**特殊处理**: +- **UTF-8 安全**: 处理 TCP 分包导致的 UTF-8 多字节字符截断，使用 `utf8_remainder` 缓冲区确保不会产生 U+FFFD 替换字符 +- **Copilot 无限空白 Bug 检测**: 跟踪连续空白字符数，超过 20 个时强制中止 tool call 流（Copilot 有时会无限输出空白字符的已知 Bug） +- **延迟工具调用**: 处理 `id/name` 在 `arguments` 之后到达的乱序情况 + +### 6.2 OpenAI Responses API SSE → Anthropic SSE + +**文件**: `src-tauri/src/proxy/providers/streaming_responses.rs` (1070 行) + +Responses API 使用**命名事件** (named events) 的生命周期模型，与 Chat Completions 的 delta chunk 模型完全不同。 + +**事件映射**: + +| Responses API SSE Event | Anthropic SSE Event | +|---|---| +| `response.created` | `message_start` | +| `response.content_part.added` (output_text) | `content_block_start(type:text)` | +| `response.output_text.delta` | `content_block_delta(text_delta)` | +| `response.refusal.delta` | `content_block_delta(text_delta)` | +| `response.output_text.done` | `content_block_stop` | +| `response.output_item.added` (function_call) | `content_block_start(type:tool_use)` | +| `response.function_call_arguments.delta` | `content_block_delta(input_json_delta)` | +| `response.function_call_arguments.done` | `content_block_stop` | +| `response.reasoning.delta` | `content_block_start(type:thinking)` + `content_block_delta(thinking_delta)` | +| `response.reasoning.done` | `content_block_stop` | +| `response.completed` | `message_delta` (stop_reason + usage) + `message_stop` | + +**状态管理**: 维护 `content_part_key` (item_id + content_index 复合键)、`index_by_key` (content part → Anthropic index 映射)、`tool_index_by_item_id` (item_id → index 映射)、`open_indices` (未关闭的 block 索引集合)。 + +### 6.3 Gemini SSE → Anthropic SSE + +**文件**: `src-tauri/src/proxy/providers/streaming_gemini.rs` (1054 行) + +Gemini 的 `streamGenerateContent?alt=sse` 每个 chunk 都是完整的 `GenerateContentResponse`，需要增量合并。 + +**核心机制**: +- **累积快照模型**: 每个 SSE chunk 包含完整的 candidates，系统通过比较 `functionCall.name` 和位置匹配来去重和合并跨 chunk 的工具调用 +- **工具调用 ID 去重合并**: `merge_tool_call_snapshots()` 处理跨 chunk 的工具调用累积（支持合成 ID → 真实 ID 升级） +- **Shadow Store 记录**: 在流结束时记录 assistant turn 到 shadow store（包括 `thoughtSignature`） +- **Tool Call Rectification**: 流式场景下同样应用工具参数修正 +- **thoughtSignature 提取**: 从 text parts 中提取 `thoughtSignature` 用于后续回放 + +--- + +## 7. 请求处理流程 + +### 7.1 主处理链 + +以 Claude Code → CC-Switch → 上游 API 为例的完整流程： + +``` +Claude Code 发送 Anthropic Messages API 请求 + │ + ▼ +[server.rs] 路由匹配 → /v1/messages → handle_messages() + │ + ▼ +[handlers.rs] handle_messages(): + 1. 解析请求体 + 2. 创建 RequestContext (识别 AppType::Claude, 提取 session_id) + 3. 调用 forwarder.forward_with_retry() + │ + ▼ +[forwarder.rs] RequestForwarder.forward_with_retry(): + 遍历供应商列表（故障转移队列）: + 1. 检查熔断器状态 + 2. forward() 内部处理: + a. get_adapter(AppType::Claude) → ClaudeAdapter + b. 提取 base_url，应用 model_mapper 映射模型名 + c. 规范化 thinking 类型 + d. 确定端点路径（Copilot 动态端点 / 格式化重写） + e. Copilot Optimizer: 分类请求、清理孤立 tool_result、合并 tool_result、热身降级、确定性 ID + f. 解析 API 格式: get_claude_api_format() + g. 如需转换: transform_claude_request_for_api_format() + - openai_chat → anthropic_to_openai() + - openai_responses → anthropic_to_responses() + - gemini_native → anthropic_to_gemini_with_shadow() + h. body_filter: 过滤 `_` 前缀的私有参数 + i. 获取动态认证 Token (Copilot/CodexOAuth) + j. 构建有序 HeaderMap + k. 发送请求 (hyper for HTTP/CONNECT proxy, reqwest for SOCKS5 proxy) + 3. 成功: 记录结果、更新状态、触发 UI 切换 + 4. 失败: 检查 thinking_rectifier / thinking_budget_rectifier，各自最多触发一次修复后重试 + │ + ▼ +[handlers.rs] 响应处理: + if needs_transform: + 流式: 根据格式选择: + - openai_responses → create_anthropic_sse_stream_from_responses() + - gemini_native → create_anthropic_sse_stream_from_gemini() + - 其他 → create_anthropic_sse_stream() + 非流式: 读取完整响应，应用: + - responses_to_anthropic() + - gemini_to_anthropic_with_shadow_and_hints() + - openai_to_anthropic() + else: + 透传响应 +``` + +### 7.2 Copilot Optimizer + +**文件**: `src-tauri/src/proxy/copilot_optimizer.rs` (1251 行) + +专用于 GitHub Copilot 的请求优化系统，在转发器内部对请求进行预处理： + +| 优化策略 | 说明 | +|---------|------| +| **请求分类** | 识别 initiator (user/agent)、热身请求、压缩请求、子代理请求 | +| **孤立 tool_result 清理** | 清理无对应 tool_use 的 tool_result（Claude Code 偶尔产生） | +| **tool_result 合并** | 将多个 tool_result 合并为一个，减少 Copilot 高级计费 | +| **热身降级** | 检测到热身请求时降级为小模型，节省成本 | +| **确定性请求 ID** | 基于 session 生成确定性 `x-request-id` 和 `x-interaction-id`，提高 Copilot 稳定性 | +| **子代理头修改** | 子代理请求时修改 `x-initiator`、`x-interaction-type` 为 agent | + +### 7.3 Thinking 自修复机制 + +**文件**: `src-tauri/src/proxy/thinking_rectifier.rs` (609 行), `thinking_budget_rectifier.rs` (307 行) + +两个独立的自修复 rectifier，在 Anthropic API 返回特定错误时自动修复并重试： + +| Rectifier | 触发条件 | 修复动作 | 触发次数限制 | +|-----------|---------|---------|------------| +| **Signature Rectifier** | Anthropic API 报告 thinking signature 无效 | 移除 `thinking`/`redacted_thinking` blocks 和 `signature` 字段 | 每请求 1 次 | +| **Budget Rectifier** | Anthropic API 报告 thinking budget 错误 | 调整 `thinking.budget_tokens` | 每请求 1 次 | + +修复后通过 `release_permit_neutral()` 释放熔断器的 HalfOpen 探测槽位，不影响健康统计。 + +### 7.4 其他辅助机制 + +| 模块 | 文件 | 行数 | 说明 | +|------|------|------|------| +| **私有参数过滤** | `body_filter.rs` | 261 | 过滤 `_` 前缀的参数，允许客户端传递控制参数而不发送到上游 | +| **缓存注入** | `cache_injector.rs` | 329 | 为 Bedrock 等支持 prompt 缓存的供应商注入缓存控制标记 | +| **Thinking 优化** | `thinking_optimizer.rs` | 230 | Bedrock 场景下的 thinking 参数优化 | +| **模型名映射** | `model_mapper.rs` | 312 | 将客户端请求的模型名映射为上游实际模型名 | +| **Gemini URL** | `gemini_url.rs` | 583 | 处理 Gemini API 的复杂 URL 构建逻辑 | +| **SSE 基础** | `sse.rs` | 294 | SSE 事件解析和生成的基础工具 | + +--- + +## 8. 熔断器与故障转移 + +### 8.1 熔断器 + +**文件**: `src-tauri/src/proxy/circuit_breaker.rs` (482 行) + +三态熔断器保护上游服务： + +| 参数 | 默认值 | +|------|-------| +| `failure_threshold` | 4 (连续失败次数) | +| `success_threshold` | 2 (连续成功次数) | +| `timeout_seconds` | 60 (Open 状态持续时间) | +| `error_rate_threshold` | 0.6 (错误率阈值) | +| `min_requests` | 10 (最小请求数) | + +**状态转换**: Closed (正常) → Open (熔断) → HalfOpen (探测，最多 1 个并发探测请求) → Closed/Open + +### 8.2 供应商路由 + +**文件**: `src-tauri/src/proxy/provider_router.rs` (512 行) + +- 故障转移关闭时：仅使用当前供应商 +- 故障转移开启时：返回按优先级排列的故障转移队列，跳过熔断中的供应商 + +--- + +## 9. 支持的协议转换矩阵 + +``` + ┌──────────────────────────────────────────────┐ + │ CC-Switch 代理 │ + │ │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + Claude Code ──────▶│ │ Claude │ │ Codex │ │ Gemini │ │ + (Anthropic │ │ Handler │ │ Handler │ │ Handler │ │ + Messages API) │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ + │ │ │ │ │ + │ ┌────▼─────────────▼──────────────▼─────┐ │ + │ │ Forwarder (转发器) │ │ + │ │ - 供应商选择 / 故障转移 / Copilot优化 │ │ + │ │ - Thinking自修复 / 参数过滤 │ │ + │ └────────────────┬───────────────────────┘ │ + │ │ │ + │ ┌───────────┼───────────┐ │ + │ ▼ ▼ ▼ │ + │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ + │ │OpenAI │ │OpenAI │ │ Gemini │ │ + │ │Chat │ │Responses│ │ Native │ │ + │ │Complet. │ │API │ │ │ │ + │ └────┬────┘ └────┬────┘ └────┬─────┘ │ + │ │ │ │ │ + └───────┼───────────┼───────────┼─────────────┘ + ▼ ▼ ▼ + ┌───────────┐ ┌──────────┐ ┌──────────────┐ + │OpenAI/ │ │ChatGPT/ │ │ Google AI │ + │OpenRouter/│ │OpenAI/ │ │ Gemini API │ + │Copilot │ │Codex OAuth│ │ │ + └───────────┘ └──────────┘ └──────────────┘ +``` + +### 转换路径汇总 + +| 转换路径 | 请求转换 | 响应转换 | 流式转换 | 使用场景 | +|---------|---------|---------|---------|---------| +| Anthropic → OpenAI Chat | `anthropic_to_openai()` | `openai_to_anthropic()` | `streaming.rs` | GitHub Copilot, OpenRouter (旧版) | +| Anthropic → OpenAI Responses | `anthropic_to_responses()` | `responses_to_anthropic()` | `streaming_responses.rs` | Codex OAuth (ChatGPT Plus/Pro) | +| Anthropic → Gemini | `anthropic_to_gemini_with_shadow()` | `gemini_to_anthropic_with_shadow_and_hints()` | `streaming_gemini.rs` | Gemini 模型直连 | +| Anthropic → Anthropic (透传) | 直接转发 | 直接转发 | 直接转发 | Anthropic 官方, OpenRouter (新版) | + +--- + +## 10. 文件索引 + +### 核心转换文件 + +| 文件路径 | 功能 | 代码行数 | +|---------|------|---------| +| `src-tauri/src/proxy/providers/transform.rs` | Anthropic ↔ OpenAI Chat Completions 转换 | 1193 | +| `src-tauri/src/proxy/providers/transform_responses.rs` | Anthropic ↔ OpenAI Responses API 转换 | 1329 | +| `src-tauri/src/proxy/providers/transform_gemini.rs` | Anthropic ↔ Gemini Native 转换 | 2152 | +| `src-tauri/src/proxy/providers/streaming.rs` | OpenAI Chat SSE → Anthropic SSE 流式转换 | 821 | +| `src-tauri/src/proxy/providers/streaming_responses.rs` | Responses SSE → Anthropic SSE 流式转换 | 1070 | +| `src-tauri/src/proxy/providers/streaming_gemini.rs` | Gemini SSE → Anthropic SSE 流式转换 | 1054 | + +### 适配器与认证 + +| 文件路径 | 功能 | 代码行数 | +|---------|------|---------| +| `src-tauri/src/proxy/providers/adapter.rs` | ProviderAdapter trait 定义 | 50 | +| `src-tauri/src/proxy/providers/auth.rs` | AuthInfo / AuthStrategy 认证类型定义 | 259 | +| `src-tauri/src/proxy/providers/claude.rs` | Claude 适配器 (API 格式检测, URL 构建, 认证) | 1313 | +| `src-tauri/src/proxy/providers/codex.rs` | Codex 适配器 | 305 | +| `src-tauri/src/proxy/providers/gemini.rs` | Gemini 适配器 | 442 | +| `src-tauri/src/proxy/providers/mod.rs` | ProviderType 枚举, get_adapter() 工厂函数 | 515 | +| `src-tauri/src/proxy/providers/copilot_auth.rs` | Copilot 动态 Token 管理 | 1820 | +| `src-tauri/src/proxy/providers/codex_oauth_auth.rs` | Codex OAuth 动态 Token 管理 | 1132 | +| `src-tauri/src/proxy/providers/gemini_shadow.rs` | Gemini Shadow Store (状态回放) | 389 | +| `src-tauri/src/proxy/providers/gemini_schema.rs` | Gemini Schema 构建 (双通道策略) | 338 | + +### 请求处理链 + +| 文件路径 | 功能 | 代码行数 | +|---------|------|---------| +| `src-tauri/src/proxy/server.rs` | Axum HTTP 服务器, 路由注册 | 354 | +| `src-tauri/src/proxy/handlers.rs` | 请求处理器 (分发 + Claude 格式转换入口) | 643 | +| `src-tauri/src/proxy/forwarder.rs` | 请求转发器 (供应商选择, 故障转移, 请求预处理) | 2169 | +| `src-tauri/src/proxy/copilot_optimizer.rs` | Copilot 请求优化 | 1251 | +| `src-tauri/src/proxy/thinking_rectifier.rs` | Thinking Signature 自修复 | 609 | +| `src-tauri/src/proxy/thinking_budget_rectifier.rs` | Thinking Budget 自修复 | 307 | +| `src-tauri/src/proxy/thinking_optimizer.rs` | Bedrock Thinking 优化 | 230 | +| `src-tauri/src/proxy/cache_injector.rs` | Prompt 缓存注入 | 329 | +| `src-tauri/src/proxy/body_filter.rs` | 私有参数过滤 (`_` 前缀) | 261 | +| `src-tauri/src/proxy/model_mapper.rs` | 模型名映射 | 312 | +| `src-tauri/src/proxy/gemini_url.rs` | Gemini URL 构建 | 583 | +| `src-tauri/src/proxy/sse.rs` | SSE 基础工具 | 294 | +| `src-tauri/src/proxy/provider_router.rs` | 供应商路由 (故障转移队列) | 512 | +| `src-tauri/src/proxy/circuit_breaker.rs` | 熔断器实现 | 482 | +| `src-tauri/src/proxy/handler_context.rs` | RequestContext 构建 | 246 | +| `src-tauri/src/proxy/response_processor.rs` | 响应处理 (透传/日志/usage) | 915 | +| `src-tauri/src/proxy/session.rs` | 会话管理 | 565 | +| `src-tauri/src/proxy/hyper_client.rs` | Hyper HTTP 客户端 | 626 | +| `src-tauri/src/proxy/http_client.rs` | Reqwest HTTP 客户端 (SOCKS5) | 392 | +| `src-tauri/src/proxy/error.rs` | 错误类型定义 | 177 | +| `src-tauri/src/proxy/error_mapper.rs` | 错误映射 | 99 | + +--- + +## 11. 关键设计特点 + +### 11.1 单方向锚定转换 + +所有转换以 Anthropic Messages API 为锚点，仅实现 Anthropic ↔ X 的双向转换。客户端协议只有一种（Anthropic Messages API），上游协议有三种（OpenAI Chat、OpenAI Responses、Gemini Native）加一种透传（Anthropic 直连）。 + +### 11.2 流式 + 非流式双轨支持 + +每种协议转换都同时实现了非流式 (JSON-to-JSON) 和流式 (SSE 事件逐事件翻译，基于 `async_stream` 异步流)。 + +### 11.3 有状态转换 (Gemini Shadow Store) + +Gemini 的 `thoughtSignature` 是有状态的，系统通过 Shadow Store 在内存中记录每轮 assistant 的原始 Gemini 响应，在后续请求中回放。这是 CC-Switch 独有的复杂机制。 + +### 11.4 自修复能力 (Thinking Rectifiers) + +两个独立 rectifier 在 API 错误时自动修复请求并重试，大幅提高了对 Anthropic API thinking 功能变更的容错能力。 + +### 11.5 Copilot 深度适配 + +Copilot Optimizer 针对性地解决了 Copilot 的多个实际问题（无限空白 Bug、请求不稳定、高级计费优化等），是与供应商深度绑定的典型案例。 + +### 11.6 请求头大小写保留 + +通过手动 hyper accept loop + TCP `peek()` 捕获原始请求头大小写，转发给上游时保持一致（部分上游 API 对 header 大小写敏感）。 + +### 11.7 代理协议支持 + +支持 HTTP/CONNECT 和 SOCKS5 两种代理协议，分别使用 hyper 和 reqwest 客户端。 + +### 11.8 UTF-8 安全 + +流式转换中处理 TCP 分包导致的 UTF-8 多字节字符截断，使用 `utf8_remainder` 缓冲区确保不会产生 U+FFFD 替换字符。 diff --git a/docs/analysis_reference/analysis_litellm.md b/docs/analysis_reference/analysis_litellm.md new file mode 100644 index 0000000..5620999 --- /dev/null +++ b/docs/analysis_reference/analysis_litellm.md @@ -0,0 +1,575 @@ +# LiteLLM 大模型 API 代理转换层深度分析报告 + +## 1. 项目概述 + +LiteLLM 是一个统一的 LLM API 网关和 SDK 项目，核心能力是将 100+ 种不同来源的大模型 API 统一管理，并以 **OpenAI 格式** 作为统一接口标准提供给用户。 + +### 整体请求流向 + +``` +OpenAI SDK (客户端) ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API +Anthropic SDK (客户端) ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API +任意 HTTP 客户端 ──▶ LiteLLM AI Gateway (proxy/) ──▶ LiteLLM SDK (litellm/) ──▶ LLM API +``` + +- **AI Gateway（代理层）**：在 SDK 之上提供认证、速率限制、预算管理和路由功能 +- **SDK（核心层）**：处理实际的 LLM 提供商调用、请求/响应转换和流式传输 + +### 与同类项目的核心差异 + +LiteLLM 是**覆盖最广**的 LLM 网关，以 **OpenAI 格式为唯一内部规范格式**（Canonical Format），所有转换都围绕 OpenAI ↔ 提供商格式展开。同时支持 **Anthropic Messages API 直通模式**（`/v1/messages` 端点），使其也能充当 Anthropic 协议的代理网关。SDK 可独立使用（Python 包），也可配合 Gateway 作为服务部署。 + +--- + +## 2. 转换层技术架构 + +### 2.1 架构设计模式 + +采用 **策略模式 + 工厂模式 + 模板方法** 组合设计： + +- **策略模式**：每个 LLM 提供商都有一个独立的 `Config` 类，继承自统一的 `BaseConfig` 抽象基类，实现各自的转换方法 +- **工厂模式**：`ProviderConfigManager` 作为中心工厂，根据模型名称和提供商类型动态解析出正确的 Config 实例 +- **模板方法**：`BaseConfig` 定义统一的转换接口（抽象方法），子类实现具体的提供商差异 + +### 2.2 核心抽象基类 + +**文件**: `litellm/llms/base_llm/chat/transformation.py` (466 行) + +```python +class BaseConfig(ABC): + @abstractmethod + def get_supported_openai_params(self, model: str) -> list: + """返回该提供商支持的 OpenAI 格式参数列表""" + + @abstractmethod + def map_openai_params(self, non_default_params, optional_params, model, drop_params) -> dict: + """将 OpenAI 格式参数映射为提供商特定参数""" + + @abstractmethod + def validate_environment(self, headers, model, messages, optional_params, ...) -> dict: + """验证并构建请求头""" + + @abstractmethod + def transform_request(self, model, messages, optional_params, litellm_params, headers) -> dict: + """将 OpenAI 格式请求转换为提供商格式""" + + @abstractmethod + def transform_response(self, model, raw_response, model_response, ...) -> ModelResponse: + """将提供商响应转换为统一的 OpenAI ModelResponse 格式""" + + @abstractmethod + def get_error_class(self, error_message, status_code, headers) -> BaseLLMException: + """返回提供商特定的错误类""" + + # 以下为有默认实现的重要方法： + def get_complete_url(self, api_base, api_key, model, ...) -> str: ... # URL 构建 + def sign_request(self, headers, optional_params, request_data, ...) -> ...: ... # 请求签名 + def get_model_response_iterator(self, ...) -> BaseModelResponseIterator: ... # 流式迭代器 + def should_fake_stream(self, ...) -> bool: ... # 是否需要模拟流式 + def is_thinking_enabled(self, ...) -> bool: ... # 思考模式检测 + def calculate_additional_costs(self, ...) -> float: ... # 自定义成本计算 + def post_stream_processing(self, ...) -> ...: ... # 流式后处理钩子 +``` + +**6 个抽象方法**必须实现，其余方法提供默认实现。 + +### 2.3 中央 HTTP 编排器 + +**文件**: `litellm/llms/custom_httpx/llm_http_handler.py` (12,161 行) + +`BaseLLMHTTPHandler` 是所有提供商共用的 HTTP 编排器，支持**多种模态**（不仅限于 chat）： + +``` +completion() 编排流程： +1. provider_config.validate_environment() → 验证环境、构建请求头 +2. provider_config.get_complete_url() → 构建 API URL +3. provider_config.transform_request() → 转换请求体 +4. provider_config.sign_request() → 签名请求（如 AWS Bedrock） +5. 发送 HTTP 请求到提供商 API +6. provider_config.transform_response() → 转换响应为 ModelResponse +``` + +**额外支持的模态**: embedding、rerank、audio_transcription、OCR、vector_store、files、batches、image_generation、video_generation、responses API 等。 + +**关键设计**: 编排器本身不需要修改，所有提供商的差异都封装在各自的 Config 类中。此外编排器还支持 **HTTP 错误重试**模式 — 通过 `should_retry_llm_api_inside_llm_translation_on_http_error()` 在特定错误时自动修复并重试。 + +### 2.4 请求入口与提供商解析 + +**入口文件**: `litellm/main.py` 的 `completion()` 函数（约 7,807 行，`completion()` 起始于 line 1052） + +**提供商解析文件**: `litellm/litellm_core_utils/get_llm_provider_logic.py` 的 `get_llm_provider()` 函数 (958 行) + +解析优先级： + +1. **LiteLLM Proxy 默认**: 检查是否应使用 litellm_proxy +2. **litellm_params**: 从 router 参数获取 +3. **Azure 特殊处理**: Azure 非 OpenAI 模型 +4. **Cohere/Anthropic 文本模型重定向** +5. **OpenRouter 前缀剥离** +6. **JSON 配置提供商**: `JSONProviderRegistry` 动态注册的 OpenAI 兼容提供商 +7. **前缀提供商**: `model.split("/")[0]` 在提供商列表中匹配 +8. **API Base 匹配**: ~40 个已知 API 端点域名匹配 +9. **已知模型名查找**: `"gpt-4"` → `"openai"`，`"claude-3"` → `"anthropic"` +10. **字符串前缀回退**: `model.startswith("bytez/")` → `"bytez"` +11. **错误**: 无法解析则抛出 `BadRequestError` + +**Config 解析**: `litellm/utils.py` 的 `ProviderConfigManager`（line 8013），通过 `_PROVIDER_CONFIG_MAP` 懒加载字典进行 O(1) 查找，约 90 个提供商映射。 + +**派发模式**: `main.py` 中仍保留一个较大的 `if/elif` 链用于提供商分派。Azure 和 OpenAI 仍使用专用处理路径，约 30 个提供商通过 `base_llm_http_handler.completion()` 处理。 + +### 2.5 多模态工厂 + +`ProviderConfigManager` 提供多个工厂方法： + +| 工厂方法 | 用途 | 提供商数量 | +|---------|------|-----------| +| `get_provider_chat_config()` | Chat Completions | ~90 | +| `get_provider_embedding_config()` | Embedding 向量 | ~25 | +| `get_provider_rerank_config()` | Rerank 重排序 | ~13 | +| `get_provider_anthropic_messages_config()` | Anthropic Messages 直通 | 4 | + +--- + +## 3. 支持的协议/提供商总览 + +### 3.1 支持规模 + +| 维度 | 数量 | +|------|------| +| LLM 提供商枚举值 (`LlmProviders`) | 133 | +| 搜索提供商枚举值 (`SearchProviders`) | 12 | +| 实现目录数 (`litellm/llms/` 下) | ~118 | +| `base_llm/` 子模态目录 | 29 (chat, embedding, rerank, responses, audio, OCR, image, video, etc.) | + +### 3.2 主要提供商分类 + +| 分类 | 提供商 | 转换方式 | +|------|--------|----------| +| **OpenAI 及兼容** | OpenAI, Azure OpenAI, DeepSeek, Groq, Together AI, Fireworks, Perplexity, OpenRouter 等 | 几乎直通，参数过滤 | +| **Anthropic 系列** | Anthropic 原生, Bedrock Claude, Vertex AI Claude | 深度转换（消息格式、工具调用、思考模式） | +| **Google 系列** | Gemini (AI Studio), Vertex AI Gemini | 深度转换（contents/parts 格式、角色映射） | +| **AWS 系列** | Bedrock Converse, Bedrock Invoke | Converse 统一格式 或 按提供商分派转换 | +| **开源/本地** | Ollama, vLLM, LM Studio, llamafile | 参数重映射 + 消息格式适配 | +| **其他云厂商** | Cohere, Mistral, Databricks, WatsonX, OCI, Snowflake 等 | 各自独立转换 | +| **直通模式** | 所有提供商 | 请求体不变，仅转换 URL 和认证头 | + +--- + +## 4. 核心转换文件详解 + +### 4.1 转换文件总览表 + +| 入站 API 协议 | 目标提供商 | 转换文件 | +|---------------|-----------|----------| +| `/v1/chat/completions` (OpenAI) | Anthropic | `litellm/llms/anthropic/chat/transformation.py` | +| `/v1/chat/completions` (OpenAI) | Bedrock Converse | `litellm/llms/bedrock/chat/converse_transformation.py` | +| `/v1/chat/completions` (OpenAI) | Bedrock Invoke | `litellm/llms/bedrock/chat/invoke_transformations/*.py` | +| `/v1/chat/completions` (OpenAI) | Gemini | `litellm/llms/gemini/chat/transformation.py` (薄层) → `litellm/llms/vertex_ai/gemini/transformation.py` (核心) | +| `/v1/chat/completions` (OpenAI) | Vertex AI | `litellm/llms/vertex_ai/vertex_ai_partner_models/main.py` | +| `/v1/chat/completions` (OpenAI) | OpenAI | `litellm/llms/openai/chat/gpt_transformation.py` | +| `/v1/chat/completions` (OpenAI) | Ollama | `litellm/llms/ollama/chat/transformation.py` | +| `/v1/chat/completions` (OpenAI) | Cohere | `litellm/llms/cohere/chat/transformation.py` | +| `/v1/chat/completions` (OpenAI) | Mistral | `litellm/llms/mistral/chat/transformation.py` | +| `/v1/messages` (Anthropic) | Anthropic/Bedrock/Vertex | `litellm/llms/base_llm/anthropic_messages/transformation.py` | +| 直通端点 | 所有 | `litellm/proxy/pass_through_endpoints/` | + +--- + +### 4.2 Anthropic 转换层 + +**文件**: `litellm/llms/anthropic/chat/transformation.py` (2,096 行) +**类**: `AnthropicConfig(AnthropicModelInfo, BaseConfig)` + +#### 请求转换（OpenAI → Anthropic） + +`transform_request()` 方法核心转换逻辑： + +1. **系统消息提取**: 将 `role: "system"` 消息从 messages 列表中提取出来，放入 Anthropic 顶层 `system` 字段（Anthropic API 不使用 system-role 消息） +2. **消息格式转换**: 调用 `anthropic_messages_pt()` 将 OpenAI 消息转为 Anthropic Messages 格式 +3. **工具调用转换**: OpenAI 的 `function.parameters` → Anthropic 的 `input_schema`；工具选择 `"required"` → `"any"`，`parallel_tool_calls: false` → `disable_parallel_tool_use: true` +4. **Beta Header 管理**: 根据使用的功能（web search、memory、structured output、computer use、code execution、MCP server 等）自动添加 `anthropic-beta` 请求头 +5. **Thinking 参数处理**: 管理 Anthropic Extended Thinking 参数 +6. **JSON 模式**: 旧模型通过创建合成工具实现 JSON 模式；新模型（Sonnet 4.5+）原生支持结构化输出 + +**关键参数映射**: + +| OpenAI 参数 | Anthropic 参数 | 说明 | +|-------------|---------------|------| +| `max_tokens` / `max_completion_tokens` | `max_tokens` | 直接映射，默认值可通过环境变量配置 | +| `tools[].function.parameters` | `tools[].input_schema` | JSON Schema 格式转换 | +| `tool_choice: "required"` | `tool_choice: {"type": "any"}` | 语义映射 | +| `parallel_tool_calls: false` | `disable_parallel_tool_use: true` | 反转布尔值 | +| `stop` | `stop_sequences` | 字符串 → 列表 | +| `response_format` (JSON) | 合成工具方式 / `output_format` | 按模型能力选择 | +| `reasoning_effort` | `thinking` + `output_config` | 努力级别映射为思考预算 | +| `web_search_options` | `tools` (web_search hosted tool) | 转换为 Anthropic 原生搜索工具 | +| `user` | `metadata.user_id` | 嵌套到 metadata | + +#### 响应转换（Anthropic → OpenAI） + +1. **内容块解析**: text → 文本, tool_use → ToolCall, thinking/redacted_thinking → `reasoning_content` + `thinking_blocks` +2. **JSON 模式逆向转换**: 如果启用了 JSON 模式，将工具调用的参数提取为文本内容 +3. **停止原因映射**: `end_turn`/`stop_sequence` → `stop`, `max_tokens` → `length`, `tool_use` → `tool_calls` +4. **Usage 计算**: 输入/输出 token、缓存 token、推理 token 等 + +--- + +### 4.3 OpenAI 转换层（基准实现） + +**文件**: `litellm/llms/openai/chat/gpt_transformation.py` (820 行) +**类**: `OpenAIGPTConfig(BaseLLMModelInfo, BaseConfig)` — 标记 `_is_base_class = True` + +OpenAI 是"原生"格式提供者，其转换层最简单： + +- **`transform_request()`**: 仅做少量规范化（image_url 格式化、移除 `cache_control`、PDF URL 转 base64） +- **`transform_response()`**: JSON 解析后直接构建 `ModelResponse` +- **`map_openai_params()`**: 简单的参数过滤（只保留支持的参数列表） + +**作为基类被复用**: +- `OpenAIOSeriesConfig` — O1/O3 推理模型（`system` 角色转 `user`，限制 temperature） +- `OpenAIGPTAudioConfig` — GPT-4o 音频模型 +- `OpenAIGPT5Config` — GPT-5 系列（推理努力级别标准化） +- 许多 OpenAI 兼容提供商（DeepSeek、Groq、Together AI 等）也复用此类 +- **Mistral** 也继承自 `OpenAIGPTConfig`（API 大部分兼容，额外处理 schema 清理和 thinking） + +--- + +### 4.4 Google Gemini 转换层 + +**文件**: +- `litellm/llms/gemini/chat/transformation.py` (154 行) — 薄层，继承 Vertex Gemini +- `litellm/llms/vertex_ai/gemini/transformation.py` (941 行) — 核心转换逻辑 + +**类继承链**: +``` +BaseConfig → VertexAIBaseConfig → VertexGeminiConfig → GoogleAIStudioGeminiConfig +``` + +#### 请求转换（OpenAI → Gemini） + +这是最复杂的转换之一： + +| 方面 | OpenAI 格式 | Gemini 格式 | +|------|-----------|------------| +| 消息容器 | `messages: [{role, content}]` | `contents: [{role, parts}]` | +| 角色类型 | `system`, `user`, `assistant`, `tool` | 仅 `user` 和 `model` | +| 内容格式 | 字符串或内容对象列表 | `PartType` 对象列表 | +| 工具结果 | 独立的 `role: "tool"` 消息 | 合并到 `role: "user"` 的 parts | +| 连续消息 | 允许任意顺序 | 必须严格交替 user/model | + +转换算法核心步骤： +1. **系统消息提取**: 放入 `system_instruction` 字段 +2. **角色映射**: `user`/`system` → `user`, `assistant` → `model`, `tool`/`function` → `user` +3. **角色交替强制**: 合并连续相同角色的消息 +4. **媒体处理**: image_url → `inline_data` (base64) 或 `file_data` (GCS URI) +5. **工具调用转换**: OpenAI `tool_calls` → Gemini `functionCall` parts +6. **搜索工具冲突处理**: 搜索工具与函数声明互斥时优先保留函数声明 + +**关键参数映射**: + +| OpenAI 参数 | Gemini 参数 | 说明 | +|-------------|-----------|------| +| `max_tokens` | `max_output_tokens` | 名称变更 | +| `stop` | `stop_sequences` | 字符串 → 列表 | +| `n` | `candidate_count` | 名称变更 | +| `response_format` | `response_mime_type` + `response_schema` | 复杂 Schema 转换 | +| `reasoning_effort` | `thinkingConfig` | 努力级别 → 思考预算 | +| `tool_choice: "none"` | `NONE` | 大写枚举 | +| `tool_choice: "required"` | `ANY` | 语义映射 | +| `modalities: ["image"]` | `responseModalities: ["IMAGE"]` | 大写枚举 | +| `web_search_options` | `tools` (googleSearch) | 转换为 Gemini 搜索工具 | + +--- + +### 4.5 AWS Bedrock 转换层 + +Bedrock 是架构最复杂的转换层，支持 **四条独立转换路径**： + +#### 路径 1：Converse API（推荐） + +**文件**: `litellm/llms/bedrock/chat/converse_transformation.py` (2,129 行) +**类**: `AmazonConverseConfig(BaseConfig)` + +使用 Bedrock 的统一 Converse API，所有提供商共享同一套请求/响应结构： + +``` +请求格式：{ + "messages": [...], # Bedrock MessageBlock 格式 + "system": [...], # SystemContentBlock 格式 + "inferenceConfig": {...}, # maxTokens, temperature, topP, topK 等 + "additionalModelRequestFields": {...}, # 提供商特定字段 + "toolConfig": {...}, # 工具配置 + "guardrailConfig": {...}, # 护栏配置 +} +``` + +支持最丰富的功能集：工具调用、思考模式、结构化输出、护栏、Web 搜索、Computer Use 等。 + +#### 路径 2：Invoke API（传统/遗留） + +**文件**: `litellm/llms/bedrock/chat/invoke_transformations/` — 15 个提供商特定文件 +**基类**: `AmazonInvokeConfig(BaseConfig, BaseAWSLLM)` + +采用 **分派模式 (Dispatcher Pattern)**：`get_bedrock_chat_config()` 从模型名解析提供商，然后委托给对应的转换类： + +``` +AmazonInvokeConfig.transform_request() + → get_bedrock_invoke_provider(model) # 从模型名解析提供商 + → 按提供商委托： + - "anthropic" → AmazonAnthropicClaudeConfig（复用 AnthropicConfig） + - "cohere" → 构建 Cohere 格式请求 + - "meta" → {"prompt": ...} 文本格式 + - "nova" → AmazonInvokeNovaConfig + - "deepseek_r1", "qwen3", "qwen2", "moonshot", "openai" 等 → 各自的转换器 +``` + +**Anthropic Claude Invoke 特殊设计**: `AmazonAnthropicClaudeConfig` 通过多重继承 `AmazonInvokeConfig + AnthropicConfig`，复用 Anthropic 原生转换逻辑，但去除 Bedrock 不兼容的字段并设置 `anthropic_version = "bedrock-2023-05-31"`。 + +#### 路径 3：Converse-like — Converse 的轻量包装器 + +#### 路径 4：Invoke Agent — Bedrock Agent 编排调用的专用路径 + +**路由决策** (`get_bedrock_chat_config()`): 先按 `bedrock_route`（converse/openai/agent/agentcore）选择路径，再按 `bedrock_invoke_provider` 选择子提供商。 + +--- + +### 4.6 Vertex AI 转换层 + +**文件**: `litellm/llms/vertex_ai/` — 多提供商门面 (Multi-Provider Facade) + +Vertex AI 在 Google Cloud 上托管了多种第三方模型： + +| 模型类型 | Config 类 / 处理方式 | 转换方式 | +|----------|----------|----------| +| Gemini | `VertexGeminiConfig` | 深度转换（同 Gemini 格式） | +| Anthropic Claude | `VertexAIAnthropicConfig` | 复用 AnthropicConfig + Vertex 认证 + `anthropic_version: "vertex-2023-10-16"` | +| Meta Llama | `OpenAILikeChatHandler` / `base_llm_http_handler` | OpenAI 兼容端点 | +| AI21 Jamba | `VertexAIAi21Config` | 继承 OpenAIGPTConfig | +| DeepSeek / Qwen / Minimax / Moonshot | `base_llm_http_handler` | OpenAI 兼容端点 | +| Mistral/Codestral | `MistralConfig` / `CodestralTextCompletionConfig` | OpenAI 兼容 | + +**调度器**: `VertexAIPartnerModels` 类通过 `PartnerModelPrefixes` 枚举（META, DEEPSEEK, MISTRAL, CODERESTAL, JAMBA, CLAUDE, QWEN, GPT_OSS 等）路由到正确的处理器。 + +--- + +### 4.7 其他重要提供商转换 + +#### Ollama（本地模型） + +**文件**: `litellm/llms/ollama/chat/transformation.py` (580 行) + +| OpenAI 参数 | Ollama 参数 | 说明 | +|-------------|-----------|------| +| `max_tokens` | `num_predict` | 名称变更 | +| `frequency_penalty` | `repeat_penalty` | 语义差异 | +| `response_format(json_object)` | `format: "json"` | 简化映射 | +| `response_format(json_schema)` | `format: ` | 直接传入 schema | +| `reasoning_effort` | `think` | 布尔/字符串 | + +支持 Ollama 特有参数（Mirostat 采样、num_ctx、num_gpu、num_thread 等），支持从 `` 标签中提取推理内容。 + +#### Cohere + +- **v1 API**: `CohereChatConfig(BaseConfig)` — 完全独立的转换（`chat_history` + 最新消息分离） +- **v2 API**: `CohereV2ChatConfig` — v2 是 OpenAI 兼容的，复用 OpenAI 转换 +- 通过 `_get_cohere_config(model)` 根据模型选择版本 + +#### Mistral + +**类**: `MistralConfig(OpenAIGPTConfig)` — **继承自 OpenAI Config**（非直接继承 BaseConfig） + +特殊处理：工具 Schema 清理（移除 `$id`、`$schema`、`additionalProperties` 等 Mistral 不支持的字段），Magistral 模型的推理通过注入专用系统提示实现。 + +--- + +### 4.8 Anthropic Messages API 直通层 + +**文件**: `litellm/llms/base_llm/anthropic_messages/transformation.py` (165 行) +**基类**: `BaseAnthropicMessagesConfig(ABC)` — **独立的**抽象基类，与 `BaseConfig` 并行 + +这是一条与标准 OpenAI 格式 `BaseConfig` 并行的转换路径，用于直接接受 Anthropic Messages API 格式（`/v1/messages`）的请求并转发到多个云提供商： + +| 提供商 | 实现类 | 认证方式 | +|--------|--------|----------| +| Anthropic 原生 | `AnthropicMessagesConfig` | API Key | +| AWS Bedrock | `BedrockModelInfo.get_bedrock_provider_config_for_messages_api()` | AWS SigV4 | +| Vertex AI Claude | `VertexAIPartnerModelsAnthropicMessagesConfig` | Google OAuth | +| Azure AI Claude | `AzureAnthropicMessagesConfig` | Azure Token | + +**关键抽象方法** (5 个): +1. `validate_anthropic_messages_environment()` — 返回 (headers, api_base) +2. `get_complete_url()` — URL 构建 +3. `get_supported_anthropic_messages_params()` — 支持的参数列表 +4. `transform_anthropic_messages_request()` — 请求转换 +5. `transform_anthropic_messages_response()` — 响应转换 + +**自修复能力**: 支持在 thinking signature 无效时自动重试（`should_retry_anthropic_messages_on_http_error()`，最多 2 次）。 + +### 4.9 Proxy 直通模式 + +**目录**: `litellm/proxy/pass_through_endpoints/` + +直通模式允许用户直接调用提供商的原生 API，**请求体不做任何转换**，仅转换： +- **URL**: 将代理路由映射到提供商的实际 API 端点 +- **认证**: 将 LiteLLM 虚拟密钥替换为提供商的 API 密钥（`PassthroughEndpointRouter` 管理凭证） +- **元数据**: 注入日志和计费信息 + +主要文件: `llm_passthrough_endpoints.py` (2,371 行)、`pass_through_endpoints.py`、`passthrough_guardrails.py` 等。 + +--- + +## 5. 流式传输处理 + +### 5.1 统一流式包装器 + +**文件**: `litellm/litellm_core_utils/streaming_handler.py` (2,418 行) +**类**: `CustomStreamWrapper` + +所有提供商共用的流式响应统一化层，实现 `__iter__`/`__next__`（同步）和 `__aiter__`/`__anext__`（异步）。 + +**核心设计**: 引入 `GenericStreamingChunk` 统一接口： +```python +GenericStreamingChunk = { + "text": str, + "is_finished": bool, + "finish_reason": str, + "usage": Usage, + "tool_use": [...], +} +``` + +所有实现了 `BaseConfig.get_model_response_iterator()` 的提供商都返回符合此格式的块，`CustomStreamWrapper` 可以统一处理。 + +**关键功能**: +- 特殊 token 处理（`<|im_start|>`, `<|im_end|>` 等） +- Stream options 支持（`include_usage`） +- 最大流式持续时间强制 +- `merge_reasoning_content_in_choices` 支持 +- `aclose()` 通过 `anyio.CancelScope` 正确清理 + +### 5.2 提供商特定的流式解析器 + +每个提供商都有独立的 `ModelResponseIterator` 实现： + +| 提供商 | 解析器位置 | 特殊处理 | +|--------|-----------|---------| +| Anthropic | `llms/anthropic/chat/handler.py` | SSE 事件类型分派（message_start/content_block_delta/message_delta） | +| OpenAI | `llms/openai/chat/gpt_transformation.py` | 几乎直通 | +| Gemini | Vertex AI 流式处理 | `contents[0].parts[0].text` 格式 | +| Bedrock Converse | `llms/bedrock/chat/converse_handler.py` | AWS 事件流格式 | +| Ollama | 内置于 transformation.py | JSON 行格式，`` 标签解析 | + +### 5.3 Fake Stream 机制 + +部分提供商（如某些 Bedrock Invoke 模型）不支持真正的流式传输。LiteLLM 通过 `should_fake_stream()` 检测这种情况，先发送非流式请求获取完整响应，然后通过 `MockResponseIterator` 逐块模拟流式输出。 + +--- + +## 6. 转换层设计模式总结 + +### 6.1 三层架构 + +``` +┌─────────────────────────────────────────┐ +│ Proxy Layer (proxy/) │ 认证、限流、路由、计费 +├─────────────────────────────────────────┤ +│ SDK Layer (litellm/) │ 统一入口、参数映射 +│ ┌─────────────────────────────────┐ │ +│ │ BaseLLMHTTPHandler │ │ HTTP 编排器（不变） +│ │ ┌───────────────────────────┐ │ │ +│ │ │ ProviderConfig (BaseConfig)│ │ │ 转换策略（可变） +│ │ │ • transform_request() │ │ │ +│ │ │ • transform_response() │ │ │ +│ │ │ • map_openai_params() │ │ │ +│ │ └───────────────────────────┘ │ │ +│ └─────────────────────────────────┘ │ +├─────────────────────────────────────────┤ +│ HTTP Client (httpx) │ 底层 HTTP 通信 +└─────────────────────────────────────────┘ +``` + +### 6.2 关键设计模式 + +| 模式 | 应用位置 | 说明 | +|------|---------|------| +| **策略模式** | `BaseConfig` + 各提供商 Config | 每个提供商的转换逻辑独立封装 | +| **工厂模式** | `ProviderConfigManager` | 根据模型/提供商动态创建 Config 实例（含子工厂） | +| **分派模式** | `AmazonInvokeConfig`, `VertexAIPartnerModels` | 根据模型名检测子提供商并委托转换 | +| **模板方法** | `BaseConfig` 抽象方法 | 定义统一的转换接口，子类实现细节 | +| **门面模式** | `VertexAIPartnerModels` | 统一入口管理多种 Vertex AI 合作模型 | +| **适配器模式** | `AmazonAnthropicClaudeConfig` | 通过多重继承适配不同 API（Bedrock + Anthropic） | +| **装饰器模式** | `CustomStreamWrapper` | 统一包装各提供商的流式响应 | + +### 6.3 转换类型分类 + +| 转换类型 | 复杂度 | 典型提供商 | 说明 | +|----------|--------|-----------|------| +| **直通型** | 低 | OpenAI, Azure, DeepSeek, Groq | 格式基本兼容，仅过滤/重命名少量参数 | +| **参数重映射型** | 中 | Ollama, Cohere v1 | 参数名称变更，消息格式基本兼容 | +| **深度转换型** | 高 | Anthropic, Gemini, Bedrock Converse | 消息结构完全不同，角色系统不同，工具调用格式不同 | +| **分派委托型** | 高 | Bedrock Invoke, Vertex AI | 根据子提供商委托到不同的转换器 | +| **直通代理型** | 极低 | Proxy 直通模式 | 仅转换 URL 和认证，请求体不变 | + +### 6.4 添加新提供商的标准流程 + +1. 在 `litellm/llms/{provider}/chat/transformation.py` 创建 Config 类 +2. 实现 `BaseConfig` 的 6 个抽象方法 +3. 在 `ProviderConfigManager._build_provider_config_map()` 中注册 +4. 在 `get_llm_provider()` 中添加提供商解析规则 +5. 在 `tests/llm_translation/test_{provider}.py` 添加单元测试 + +--- + +## 7. 关键目录结构图 + +``` +litellm/ +├── main.py # 统一入口：completion(), acompletion() (7,807行) +├── utils.py # ProviderConfigManager, 工厂方法 (9,568行) +├── types/ +│ ├── llms/openai.py # OpenAI 格式类型定义 +│ └── utils.py # LlmProviders 枚举 (133个), SearchProviders 枚举 (12个) +├── llms/ +│ ├── base_llm/ # 抽象基类目录 (29子目录, 覆盖多种模态) +│ │ ├── chat/transformation.py # ★ BaseConfig 抽象基类 (466行) +│ │ ├── anthropic_messages/ # Anthropic Messages 直通基类 +│ │ ├── embedding/ # Embedding 基类 +│ │ ├── rerank/ # Rerank 基类 +│ │ └── ... (其他模态) +│ ├── custom_httpx/ +│ │ ├── llm_http_handler.py # ★ BaseLLMHTTPHandler 编排器 (12,161行) +│ │ └── http_handler.py # HTTP 客户端封装 +│ ├── anthropic/chat/transformation.py # Anthropic 转换 (2,096行) +│ ├── openai/chat/gpt_transformation.py # OpenAI 转换 (820行) +│ ├── gemini/chat/transformation.py # Gemini 转换 (薄层, 154行) +│ ├── vertex_ai/gemini/transformation.py # Gemini 核心转换 (941行) +│ ├── vertex_ai/vertex_ai_partner_models/ # Vertex AI 合作模型门面 +│ ├── bedrock/chat/ +│ │ ├── converse_transformation.py # Bedrock Converse 转换 (2,129行) +│ │ └── invoke_transformations/ # Bedrock Invoke (15个子提供商) +│ ├── ollama/chat/transformation.py # Ollama 转换 (580行) +│ ├── cohere/chat/transformation.py # Cohere 转换 (373行) +│ ├── mistral/chat/transformation.py # Mistral 转换 (686行, 继承OpenAI) +│ └── ... (~118 个提供商目录) +├── litellm_core_utils/ +│ ├── streaming_handler.py # CustomStreamWrapper 统一流式处理 (2,418行) +│ └── get_llm_provider_logic.py # 提供商解析逻辑 (958行) +├── proxy/ +│ └── pass_through_endpoints/ # 直通代理模式 (含凭证管理) +└── router.py # 负载均衡、故障转移 +``` + +--- + +## 8. 总结 + +LiteLLM 的转换层是一个设计精良的**统一 API 网关转换引擎**，其核心优势在于： + +1. **高度模块化**: 每个提供商的转换逻辑完全独立，修改一个提供商不影响其他提供商 +2. **统一抽象**: 所有提供商通过 `BaseConfig` 接口统一管理，编排器不需要感知提供商差异 +3. **广泛覆盖**: 支持 133 个 LLM 提供商、12 个搜索提供商，涵盖所有主流云厂商、开源模型和本地部署 +4. **多协议支持**: 同时支持 OpenAI Chat Completions、Anthropic Messages (直通)、Gemini GenerateContent 等多种协议 +5. **多模态支持**: 29 个 base_llm 子目录覆盖 Chat、Embedding、Rerank、Audio、OCR、Image、Video、Responses API 等模态 +6. **可扩展性**: 添加新提供商只需实现一个 Config 类并注册 +7. **流式兼容**: 通过 `GenericStreamingChunk` + `CustomStreamWrapper` (2,418行) 统一处理所有提供商的流式响应 +8. **自修复能力**: 支持 HTTP 错误时自动重试和修复（thinking signature、请求体重构等） diff --git a/docs/analysis_reference/analysis_new-api.md b/docs/analysis_reference/analysis_new-api.md new file mode 100644 index 0000000..da6ceef --- /dev/null +++ b/docs/analysis_reference/analysis_new-api.md @@ -0,0 +1,507 @@ +# New-API 项目 API 代理转换层详细分析报告 + +## 一、项目概述 + +`new-api` 是一个用 Go 语言编写的 AI API 网关/代理项目，基于 Gin Web 框架和 GORM ORM 构建。其核心功能是将 30+ 种上游 AI 服务提供商（OpenAI、Claude/Anthropic、Google Gemini、AWS Bedrock、阿里通义千问、百度文心等）的 API 统一管理，并以标准化格式对外提供统一入口。 + +### 与同类项目的核心差异 + +New-API 是 One-API 的增强分支，在 One-API 的 OpenAI-only 输入基础上增加了**多协议输入**能力（同时接受 OpenAI、Claude、Gemini 三种格式的客户端请求）和 **Hub-and-Spoke 转换架构**（以 OpenAI 格式为内部枢纽）。同时引入了 **Chat Completions via Responses API** 内部路由、**Thinking-to-Content** 转换、异步任务适配器等高级特性。 + +--- + +## 二、技术架构 + +### 2.1 分层架构 + +项目采用经典的分层架构：**Router → Controller → Relay Handler → Adaptor → Upstream API** + +``` +┌──────────────────────────────────────────────────────────────┐ +│ 客户端请求 │ +│ (OpenAI / Claude / Gemini / Embedding / Audio / Image ...) │ +└───────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ router/relay-router.go │ +│ 路由层：URL路径 → RelayFormat 映射 │ +│ /v1/chat/completions → RelayFormatOpenAI │ +│ /v1/messages → RelayFormatClaude │ +│ /v1beta/models/* → RelayFormatGemini │ +│ /v1/responses → RelayFormatOpenAIResponses │ +│ /v1/embeddings → RelayFormatEmbedding ... │ +└───────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ controller/relay.go │ +│ 控制器层：请求验证、计费预扣、重试循环 │ +│ │ +│ Relay() 函数： │ +│ 1. 解析验证请求 (GetAndValidateRequest) │ +│ 2. 生成 RelayInfo (GenRelayInfo) │ +│ 3. Token估算 + 敏感词检测 │ +│ 4. 价格计算 + 预扣费 │ +│ 5. 渠道选择 + 重试循环 │ +│ 6. 按 RelayFormat 分发到 Handler │ +└───────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ relay/ 目录 - Handler + Adaptor 层 │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │compatible_handler│ │claude_handler.go │ │ +│ │ (OpenAI格式) │ │ (Claude格式) │ │ +│ └────────┬─────────┘ └────────┬─────────┘ │ +│ │ │ │ +│ ┌────────┴─────────┐ ┌────────┴─────────┐ │ +│ │gemini_handler.go │ │responses_handler │ │ +│ │ (Gemini格式) │ │ (Responses API) │ │ +│ └────────┬─────────┘ └────────┬─────────┘ │ +│ └──────────┬───────────┘ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ relay/relay_adaptor.go │ │ +│ │ GetAdaptor(apiType) → channel.Adaptor │ │ +│ └──────────────────────┬───────────────────────────┘ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ relay/channel/adapter.go (Adaptor接口) │ │ +│ │ ConvertOpenAIRequest() - OpenAI格式请求转换 │ │ +│ │ ConvertClaudeRequest() - Claude格式请求转换 │ │ +│ │ ConvertGeminiRequest() - Gemini格式请求转换 │ │ +│ │ ConvertEmbeddingRequest() / Audio / Image / Rerank│ │ +│ │ ConvertOpenAIResponsesRequest() - Responses转换 │ │ +│ │ DoRequest() + DoResponse() │ │ +│ └──────────────────────┬───────────────────────────┘ │ +└─────────────────────────┼────────────────────────────────────┘ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ 上游 AI 服务提供商 │ +│ OpenAI / Claude / Gemini / AWS Bedrock / 阿里 / 百度 / ... │ +└──────────────────────────────────────────────────────────────┘ +``` + +### 2.2 核心设计模式 + +项目采用 **适配器模式 + Hub-and-Spoke 架构**： + +1. **统一接口 (`channel.Adaptor`)**：定义所有提供商必须实现的转换方法 +2. **工厂函数 (`GetAdaptor`)**：根据 `apiType` 创建对应提供商的适配器实例 +3. **Hub-and-Spoke 转换架构**：以 OpenAI 格式作为内部规范格式（Canonical Format），所有其他格式先转换为 OpenAI 格式，再由 OpenAI 格式转换为目标格式 + +### 2.3 关键接口定义 + +**同步请求适配器接口** (`relay/channel/adapter.go`, 83 行)： + +```go +type Adaptor interface { + Init(info *relaycommon.RelayInfo) + GetRequestURL(info *relaycommon.RelayInfo) (string, error) + SetupRequestHeader(c *gin.Context, req *http.Header, info *relaycommon.RelayInfo) error + ConvertOpenAIRequest(c, info, request *dto.GeneralOpenAIRequest) (any, error) + ConvertClaudeRequest(c, info, request *dto.ClaudeRequest) (any, error) + ConvertGeminiRequest(c, info, request *dto.GeminiChatRequest) (any, error) + ConvertRerankRequest(c, relayMode int, request dto.RerankRequest) (any, error) + ConvertEmbeddingRequest(c, info, request dto.EmbeddingRequest) (any, error) + ConvertAudioRequest(c, info, request dto.AudioRequest) (io.Reader, error) + ConvertImageRequest(c, info, request dto.ImageRequest) (any, error) + ConvertOpenAIResponsesRequest(c, info, request dto.OpenAIResponsesRequest) (any, error) + DoRequest(c, info, requestBody io.Reader) (any, error) + DoResponse(c, resp, info) (usage any, err *types.NewAPIError) + GetModelList() []string + GetChannelName() string +} +``` + +**异步任务适配器接口** (`TaskAdaptor`)：16 个方法，覆盖任务提交、轮询、计费估算等全生命周期。 + +--- + +## 三、支持的协议/格式类型 + +### 3.1 输入格式（RelayFormat） + +**文件**: `types/relay_format.go` (19 行) + +| RelayFormat 常量 | 值 | 对应路由 | +|---|---|---| +| `RelayFormatOpenAI` | `"openai"` | `/v1/chat/completions`, `/v1/completions`, `/v1/moderations` | +| `RelayFormatClaude` | `"claude"` | `/v1/messages` | +| `RelayFormatGemini` | `"gemini"` | `/v1beta/models/*`, `/v1/engines/:model/embeddings` | +| `RelayFormatOpenAIResponses` | `"openai_responses"` | `/v1/responses` | +| `RelayFormatOpenAIResponsesCompaction` | `"openai_responses_compaction"` | `/v1/responses/compact` | +| `RelayFormatOpenAIAudio` | `"openai_audio"` | `/v1/audio/*` | +| `RelayFormatOpenAIImage` | `"openai_image"` | `/v1/images/*` | +| `RelayFormatOpenAIRealtime` | `"openai_realtime"` | `/v1/realtime` (WebSocket) | +| `RelayFormatRerank` | `"rerank"` | `/v1/rerank` | +| `RelayFormatEmbedding` | `"embedding"` | `/v1/embeddings` | +| `RelayFormatTask` | `"task"` | 异步任务 (Suno/Video等) | +| `RelayFormatMjProxy` | `"mj_proxy"` | `/mj/*` | + +### 3.2 上游提供商 API 类型 + +**文件**: `constant/api_type.go` (40 行) + +定义 35 种 API 类型（iota 0-34, 加 APITypeDummy=35），工厂函数 `GetAdaptor()` 映射了其中 29 种（其余复用 OpenAI 适配器或未使用）： + +| API 类型 | 提供商 | 适配器目录 | +|---|---|---| +| `APITypeOpenAI` (0) | OpenAI / Azure / OpenRouter / Xinference | `relay/channel/openai/` | +| `APITypeAnthropic` (1) | Anthropic Claude | `relay/channel/claude/` | +| `APITypeGemini` (9) | Google Gemini | `relay/channel/gemini/` | +| `APITypeAws` (13) | AWS Bedrock | `relay/channel/aws/` | +| `APITypeAli` (5) | 阿里云通义千问 | `relay/channel/ali/` | +| `APITypeBaidu` (3) / `APITypeBaiduV2` (24) | 百度文心 | `relay/channel/baidu/`, `baidu_v2/` | +| `APITypeZhipu` (4) / `APITypeZhipuV4` (10) | 智谱AI (GLM) | `relay/channel/zhipu/`, `zhipu_4v/` | +| `APITypeXunfei` (6) | 科大讯飞 | `relay/channel/xunfei/` | +| `APITypeTencent` (8) | 腾讯混元 | `relay/channel/tencent/` | +| `APITypeOllama` (11) | Ollama | `relay/channel/ollama/` | +| `APITypeDeepSeek` (21) | DeepSeek | `relay/channel/deepseek/` | +| `APITypeVolcEngine` (23) | 火山引擎 | `relay/channel/volcengine/` | +| `APITypeVertexAi` (19) | Google Vertex AI | `relay/channel/vertex/` | +| `APITypeMistral` (20) | Mistral AI | `relay/channel/mistral/` | +| `APITypeCohere` (14) | Cohere | `relay/channel/cohere/` | +| `APITypeOpenRouter` (25) | OpenRouter | 复用 `openai/` | +| `APITypeXai` (27) | xAI (Grok) | `relay/channel/xai/` | +| `APITypeCoze` (28) | 扣子 | `relay/channel/coze/` | +| `APITypeMoonshot` (30) | Moonshot (月之暗面) | `relay/channel/moonshot/` | +| `APITypeMiniMax` (32) | MiniMax | `relay/channel/minimax/` | +| `APITypeCodex` (34) | Codex | `relay/channel/codex/` | +| ... 其他 | SiliconFlow, Cloudflare, Perplexity, Dify, Jina, Jimeng, MokaAI, Replicate, Submodel | 各自目录 | + +--- + +## 四、转换层核心业务逻辑 + +### 4.1 格式转换核心 — Hub-and-Spoke 模式 + +项目以 **OpenAI 格式作为内部规范格式（Canonical Format）**，采用 Hub-and-Spoke 转换架构： + +``` + 客户端输入格式 + ┌──────┬──────┬───────┐ + │OpenAI│Claude│Gemini │ ... + └──┬───┴──┬───┴──┬────┘ + │ │ │ + ▼ ▼ ▼ + ┌─────────────────────────┐ + │ OpenAI 规范格式 (Hub) │ + │ dto.GeneralOpenAIRequest │ + └────────────┬──────────────┘ + │ + ┌──────┼──────┐ + ▼ ▼ ▼ + ┌──────┐┌──────┐┌──────┐ + │OpenAI││Claude││Gemini│ ... (上游格式) + └──┬───┘└──┬───┘└──┬───┘ + │ │ │ + ▼ ▼ ▼ + 上游API 上游API 上游API +``` + +**请求转换方向**： +- `Claude → OpenAI → 上游原生格式`（如上游是 Gemini: `Claude → OpenAI → Gemini`，链式转换） +- `Gemini → OpenAI → 上游原生格式` +- `OpenAI → 上游原生格式`（直接转换） + +**响应转换方向**： +- `上游原生格式 → OpenAI → 客户端格式` +- 如客户端请求 Claude 格式且上游是 Gemini: `Gemini → OpenAI → Claude` + +### 4.2 转换链跟踪 (RequestConversionChain) + +`RelayInfo` 中维护 `RequestConversionChain []types.RelayFormat` 字段，记录请求格式变化轨迹。例如： + +- 用户发送 OpenAI 格式，上游是 Claude：`["openai", "claude"]` +- 用户发送 Claude 格式，上游是 OpenAI 兼容：`["claude", "openai"]` +- 用户发送 Claude 格式，上游是 Gemini：`["claude", "openai", "gemini"]`（链式转换） + +`FinalRequestRelayFormat` 记录最终发送到上游的格式。 + +--- + +## 五、核心转换实现 + +### 5.1 核心转换服务层 — `service/convert.go` (~1007 行) + +这是整个项目的**中心格式转换库**，包含 OpenAI ↔ Claude、OpenAI ↔ Gemini 的双向转换函数： + +| 函数 | 转换方向 | 位置 | +|---|---|---| +| `ClaudeToOpenAIRequest()` | Claude 请求 → OpenAI 请求 | line 17 | +| `GeminiToOpenAIRequest()` | Gemini 请求 → OpenAI 请求 | line 658 | +| `ResponseOpenAI2Claude()` | OpenAI 响应 → Claude 响应 | line 607 | +| `StreamResponseOpenAI2Claude()` | OpenAI 流式 → Claude 流式 | line 255 | +| `ResponseOpenAI2Gemini()` | OpenAI 响应 → Gemini 响应 | line 828 | +| `StreamResponseOpenAI2Gemini()` | OpenAI 流式 → Gemini 流式 | line 907 | + +### 5.2 Claude 适配器 — `relay/channel/claude/` + +| 文件 | 行数 | 功能 | +|---|---|---| +| `relay-claude.go` | ~1009 | Claude 原生请求/响应转换 + 流式处理 | +| `adaptor.go` | ~134 | 适配器实现 | +| `dto.go` | — | Claude DTO 定义 | +| `constants.go` | — | Claude 模型列表 | + +**关键转换函数**: +- `RequestOpenAI2ClaudeMessage()` — OpenAI→Claude 请求转换 (line 47): 工具转换 (function→input_schema)、Web Search 工具、tool_choice 映射 (required→any, named→tool)、parallel_tool_calls→disable_parallel_tool_use、Thinking adapter (Opus 4.6/4.7 adaptive/enabled 模式、ReasoningEffort→BudgetTokens 映射)、OpenRouter reasoning 参数覆盖、消息角色映射、媒体内容 (image/PDF→base64 source) +- `StreamResponseClaude2OpenAI()` / `ResponseClaude2OpenAI()` — Claude→OpenAI 响应转换 +- `mapToolChoice()` — OpenAI tool_choice → Claude tool_choice + +### 5.3 Gemini 适配器 — `relay/channel/gemini/` + +| 文件 | 行数 | 功能 | +|---|---|---| +| `relay-gemini.go` | ~1900 | Gemini 原生请求/响应转换 + Thinking adapter + 原生直通处理 | +| `adaptor.go` | ~287 | 适配器实现，支持多级链式转换 | +| `relay-gemini-native.go` | 97 | Gemini 原生格式直通处理 | + +**关键转换函数**: +- `CovertOpenAI2Gemini()` — OpenAI→Gemini 请求转换 (line 201): GenerationConfig 映射、ThinkingAdaptor (thinking 后缀/budget clamp/effort level)、安全设置、工具转换 (tools→functionDeclarations + googleSearch/codeExecution/urlContext)、tool_choice→Gemini ToolConfig、ResponseFormat→responseMimeType+responseSchema、角色映射 (assistant→model, system→SystemInstructions)、Markdown 图片检测、ThoughtSignature bypass、Schema 清理 +- `ThinkingAdaptor()` — Thinking 配置适配 (line 134): 支持 `-thinking`、`-thinking-`、`-nothinking` 后缀，model-specific budget clamp +- `responseGeminiChat2OpenAI()` / `streamResponseGeminiChat2OpenAI()` — Gemini→OpenAI 响应转换 + +**Gemini 适配器的链式转换支持**: +- `ConvertClaudeRequest()`: 先通过 OpenAI 适配器 Claude→OpenAI，再 ConvertOpenAIRequest() 转 Gemini +- `DoResponse()`: 先 Gemini→OpenAI，再根据客户端格式转 Claude/Gemini 输出 + +### 5.4 OpenAI 适配器 — `relay/channel/openai/` + +| 文件 | 行数 | 功能 | +|---|---|---| +| `adaptor.go` | ~683 | OpenAI 适配器实现，含 Claude/Gemini→OpenAI 入口 | +| `relay-openai.go` | ~718 | OpenAI 响应处理，含多格式输出分发 | +| `helper.go` | ~261 | 流式格式分发器 `HandleStreamFormat()` | +| `chat_via_responses.go` | ~550 | Chat Completions via Responses API 模式 | +| `relay_responses.go` | ~150 | Responses API 原生处理 | +| `relay_responses_compact.go` | ~44 | Responses Compact API 处理 | + +**`HandleStreamFormat()`** — 流式响应核心分发器 (helper.go line 22): +```go +switch info.RelayFormat { +case types.RelayFormatClaude: + handleClaudeFormat(c, data, info) // → service.StreamResponseOpenAI2Claude +case types.RelayFormatGemini: + handleGeminiFormat(c, data, info) // → service.StreamResponseOpenAI2Gemini +default: + sendStreamData(c, data) // 直接透传 OpenAI 格式 (含 forceFormat/thinkToContent) +} +``` + +### 5.5 Chat Completions ↔ Responses API 转换 — `service/openaicompat/` + +| 文件 | 行数 | 功能 | +|---|---|---| +| `chat_to_responses.go` | ~402 | Chat Completions → Responses API | +| `responses_to_chat.go` | ~133 | Responses API → Chat Completions | +| `policy.go` | 19 | 基于正则的策略路由：判断是否将 Chat 请求路由到 Responses API | + +**Chat-via-Responses 优化**: 当配置开启时（通过正则策略匹配模型名），系统将 Chat Completions 请求内部转换为 Responses API 格式发送，再将响应转回 Chat 格式。这允许在不改变客户端 API 的前提下利用 Responses API 的独有特性（reasoning summaries、built-in tools）。 + +### 5.6 其他提供商适配器 + +| 提供商 | 转换逻辑 | +|---|---| +| **阿里 (ali/)** | OpenAI→DashScope 格式；Claude 先→OpenAI→阿里；支持 qwen 模型 Claude 兼容；异步图片生成 (X-DashScope-Async) | +| **AWS Bedrock (aws/)** | OpenAI→Claude 格式（通过 claude 包转换）；支持 Nova 模型特殊处理；API Key + AKSK 双认证模式 | +| **Ollama (ollama/)** | OpenAI→Ollama `/api/chat` 或 `/api/generate`；Claude 先→OpenAI→Ollama | +| **百度 (baidu/, baidu_v2/)** | OpenAI→百度文心格式 | +| **智谱 (zhipu/, zhipu_4v/)** | OpenAI→智谱 GLM 格式 | +| **讯飞 (xunfei/)** | OpenAI→讯飞星火格式 | +| **腾讯 (tencent/)** | OpenAI→腾讯混元格式 | +| **火山引擎 (volcengine/)** | OpenAI→火山引擎格式 | +| **Vertex AI (vertex/)** | 继承 Gemini 适配器，添加 Google Cloud 认证 | +| **DeepSeek / Mistral** | OpenAI 兼容（基础直通） | + +--- + +## 六、详细转换流程分析 + +### 6.1 场景一：用户发送 OpenAI 格式，上游是 Claude + +**请求路径**: `POST /v1/chat/completions` → Claude 上游 + +``` +1. 路由层: RelayFormatOpenAI → controller.Relay() +2. 控制器: relayHandler() → relay.TextHelper() +3. TextHelper(): + a. 解析请求 → dto.GeneralOpenAIRequest + b. GetAdaptor(APITypeAnthropic) → claude.Adaptor + c. adaptor.ConvertOpenAIRequest() → RequestOpenAI2ClaudeMessage() + - 角色映射、工具转换、thinking adapter、参数映射 + d. 发送到 Claude /v1/messages 端点 +4. DoResponse(): + - 流式: ClaudeStreamHandler() → StreamResponseClaude2OpenAI() + - 非流式: ClaudeHandler() → ResponseClaude2OpenAI() + 转换链: ["openai", "claude"] +``` + +### 6.2 场景二：用户发送 Claude 格式，上游是 Gemini + +**请求路径**: `POST /v1/messages` → Gemini 上游 + +``` +1. 路由层: RelayFormatClaude → controller.Relay() +2. 控制器: ClaudeHelper() +3. ClaudeHelper(): + a. 解析请求 → dto.ClaudeRequest + b. Thinking adapter (Opus 模型) + c. 可选: Chat-via-Responses 桥接 + d. GetAdaptor(APITypeGemini) → gemini.Adaptor + e. adaptor.ConvertClaudeRequest(): + - 第一步: openai.Adaptor.ConvertClaudeRequest() → ClaudeToOpenAIRequest() + - 第二步: CovertOpenAI2Gemini() → Gemini 格式 + - 转换链: ["claude", "openai", "gemini"] + f. 发送到 Gemini generateContent 端点 +4. DoResponse(): + - 流式: GeminiChatStreamHandler() → streamResponseGeminiChat2OpenAI() + 再根据客户端格式: service.StreamResponseOpenAI2Claude() + - 非流式: GeminiChatHandler() → responseGeminiChat2OpenAI() + 再根据客户端格式: service.ResponseOpenAI2Claude() +``` + +### 6.3 场景三：用户发送 Gemini 格式，上游是 OpenAI + +**请求路径**: `POST /v1beta/models/gemini-pro:generateContent` → OpenAI 上游 + +``` +1. 路由层: RelayFormatGemini → GeminiHelper() +2. GeminiHelper(): + a. 解析请求 → dto.GeminiChatRequest + b. Thinking adapter + c. adaptor.ConvertGeminiRequest(): Gemini→OpenAI (GeminiToOpenAIRequest) + d. 发送到 OpenAI /v1/chat/completions +3. DoResponse(): + - OpenAI 响应 → Gemini 格式 (ResponseOpenAI2Gemini / StreamResponseOpenAI2Gemini) + 转换链: ["gemini", "openai"] +``` + +### 6.4 场景四：Chat Completions 经由 Responses API + +``` +1. POST /v1/chat/completions +2. TextHelper() 检测到 ShouldChatCompletionsUseResponsesGlobal() 为 true +3. chatCompletionsViaResponses(): + a. ChatCompletionsRequestToResponsesRequest() — Chat → Responses API + b. adaptor.ConvertOpenAIResponsesRequest() — 转换为上游格式 + c. 发送请求到上游 /v1/responses + d. OaiResponsesToChatHandler() / OaiResponsesToChatStreamHandler() — Responses → Chat + e. 如果客户端格式是 Claude/Gemini，继续转换为对应格式 + 转换链: ["openai", "openai_responses"] +``` + +--- + +## 七、特殊功能与高级特性 + +### 7.1 Pass-Through 模式 + +当全局 `PassThroughRequestEnabled` 或渠道 `PassThroughBodyEnabled` 启用时，请求体直接透传到上游，跳过所有格式转换。 + +### 7.2 字段过滤 (RemoveDisabledFields) + +根据渠道安全设置过滤敏感字段: `service_tier`、`inference_geo`、`speed`、`store`、`safety_identifier`、`stream_options.include_obfuscation`。 + +### 7.3 参数覆写 (ParamOverride) + +通过 `relay/common/override.go` 支持请求参数覆写（如强制 temperature、max_tokens）。 + +### 7.4 模型名称映射 + +支持将用户请求的模型名称映射为上游实际模型名称（渠道级配置）。 + +### 7.5 Thinking/Reasoning 适配 + +- **Claude**: `-thinking` 后缀 → 启用 extended thinking + BudgetTokens；Opus 4.6/4.7 adaptive 模式 +- **Gemini**: `ThinkingAdaptor()` 支持 `-thinking`、`-thinking-`、`-nothinking` 后缀；model-specific budget clamp +- **OpenAI**: o-series 模型 → `-high/-medium/-low` 推理力度后缀 + +### 7.6 Thinking-to-Content 转换 + +渠道设置 `ThinkingToContent` 启用时，将 reasoning content 转换为带有 `...` 标签的普通文本内容，供不支持 reasoning 字段的客户端使用。 + +### 7.7 StreamOptions 适配 + +对支持 `stream_options` 的渠道自动添加 `include_usage: true` 以获取流式用量信息。 + +### 7.8 SSE Ping Keep-Alive + +内置 ping 机制保持长时间流式连接活跃。 + +### 7.9 Header 覆写/透传 + +复杂的 Header 管理系统：支持占位符替换 (`{api_key}`, `{client_header:name}`)、正则规则透传、渠道级覆写。 + +### 7.10 异步任务适配器 (TaskAdaptor) + +对视频/音乐等异步生成任务使用独立的 `TaskAdaptor` 接口，支持：任务提交、轮询、计费估算。覆盖平台：Suno、Kling、Jimeng、Vidu、Doubao、Sora、Gemini、Vertex AI、Hailuo 等。 + +--- + +## 八、转换矩阵总结 + +### 请求转换矩阵 + +| 客户端 \ 上游 | OpenAI | Claude | Gemini | Ali | AWS | Ollama | +|---|---|---|---|---|---|---| +| **OpenAI** | 直通 | OpenAI→Claude | OpenAI→Gemini | OpenAI→Ali | OpenAI→Claude(Bedrock) | OpenAI→Ollama | +| **Claude** | Claude→OpenAI | 直通 | Claude→OpenAI→Gemini | Claude→OpenAI→Ali | 直通 | Claude→OpenAI→Ollama | +| **Gemini** | Gemini→OpenAI | Gemini→OpenAI→Claude | 直通 | × | × | × | + +### 响应转换矩阵 + +| 上游 \ 客户端 | OpenAI | Claude | Gemini | +|---|---|---|---| +| **OpenAI** | 直通 | OpenAI→Claude | OpenAI→Gemini | +| **Claude** | Claude→OpenAI | 直通 | Claude→OpenAI→Gemini | +| **Gemini** | Gemini→OpenAI | Gemini→OpenAI→Claude | 直通 | +| **Ali/Ollama/其他** | →OpenAI | →OpenAI→Claude | × | + +--- + +## 九、关键文件索引 + +| 文件路径 | 行数 | 功能 | +|---|---|---| +| `relay/channel/adapter.go` | 83 | Adaptor/TaskAdaptor 接口定义 | +| `relay/relay_adaptor.go` | 165 | 适配器工厂函数 GetAdaptor/GetTaskAdaptor | +| `types/relay_format.go` | 19 | RelayFormat 类型定义 | +| `constant/api_type.go` | 40 | API 类型常量 (35种) | +| `service/convert.go` | ~1007 | **核心转换库** (OpenAI↔Claude↔Gemini) | +| `relay/channel/claude/relay-claude.go` | ~1009 | Claude 原生格式转换 | +| `relay/channel/gemini/relay-gemini.go` | ~1900 | Gemini 原生格式转换 + Thinking adapter | +| `relay/channel/gemini/relay-gemini-native.go` | 97 | Gemini 原生直通处理 | +| `relay/channel/openai/adaptor.go` | ~683 | OpenAI 适配器 (含 Claude/Gemini 入口) | +| `relay/channel/openai/helper.go` | ~261 | 流式格式分发器 HandleStreamFormat | +| `relay/channel/openai/relay-openai.go` | ~718 | OpenAI 响应处理 (含 WebSocket 代理) | +| `relay/channel/openai/chat_via_responses.go` | ~550 | Chat→Responses 内部路由 | +| `service/openaicompat/chat_to_responses.go` | ~402 | Chat→Responses 转换 | +| `service/openaicompat/responses_to_chat.go` | ~133 | Responses→Chat 转换 | +| `relay/common/relay_info.go` | ~890 | RelayInfo 上下文对象 | +| `relay/common/request_conversion.go` | 40 | 转换链跟踪 | +| `controller/relay.go` | ~647 | 主控制器 (含重试循环) | +| `router/relay-router.go` | 224 | 路由定义 | +| `relay/compatible_handler.go` | 217 | OpenAI 格式文本请求处理 (TextHelper) | +| `relay/claude_handler.go` | 214 | Claude 格式请求处理 (ClaudeHelper) | +| `relay/gemini_handler.go` | 293 | Gemini 格式请求处理 (GeminiHelper) | +| `relay/responses_handler.go` | 161 | Responses API 处理 | +| `relay/chat_completions_via_responses.go` | 161 | Chat-via-Responses 桥接处理 | + +--- + +## 十、总结 + +`new-api` 的转换层是一个**多协议 Hub-and-Spoke API 网关转换系统**，核心特点： + +1. **Hub-and-Spoke 架构**: 以 OpenAI 格式为枢纽，避免 O(n²) 的转换矩阵，通过链式转换支持任意输入/输出格式组合 +2. **多格式输入**: 同一上游提供商可接受 OpenAI、Claude、Gemini 三种主流格式，通过 `RequestConversionChain` 跟踪转换路径 +3. **统一适配器接口**: `channel.Adaptor` 接口抽象所有提供商差异，新提供商只需实现该接口 +4. **Chat-via-Responses 优化**: 在不改变客户端 API 的前提下内部路由到 Responses API，利用其独有特性 +5. **Thinking 深度适配**: Claude/Gemini/OpenAI 三种 thinking/reasoning 模式均有完善的参数适配 +6. **流式实时转换**: SSE 流式响应逐块格式转换，包括复杂的状态机管理 +7. **异步任务支持**: 独立 `TaskAdaptor` 接口覆盖视频/音乐生成等异步场景 +8. **计费深度集成**: 转换层与预扣费、结算、退款等完整计费生命周期集成 diff --git a/docs/analysis_reference/analysis_one_api.md b/docs/analysis_reference/analysis_one_api.md new file mode 100644 index 0000000..6ea89a6 --- /dev/null +++ b/docs/analysis_reference/analysis_one_api.md @@ -0,0 +1,667 @@ +# One-API 项目转换层深度分析报告 + +## 一、项目概览 + +One-API 是一个基于 Go 语言（Gin 框架）开发的大模型 API 网关代理项目。其核心功能是：**将用户发来的统一 OpenAI 格式请求，转换为各家大模型厂商的原生 API 格式，转发请求后，再将厂商的响应统一转换回 OpenAI 格式返回给用户**。 + +对外暴露的接口完全兼容 OpenAI API 规范，用户只需更改 `base_url` 和 `api_key` 即可使用。 + +### 与同类项目的核心差异 + +One-API 是此类项目的**鼻祖和基线**，采用最简单的架构模式——仅支持 OpenAI 格式作为唯一输入/输出协议，所有转换都是 **OpenAI ↔ 厂商原生格式** 的双向转换。New-API 在其基础上增加了 Claude/Gemini 输入支持和 Hub-and-Spoke 架构。One-API 的设计追求简洁实用：56 种渠道类型通过三层映射归并为 19 种 API 类型，其中 18 种 OpenAI 兼容渠道直接复用同一适配器，实现零开销透传。 + +--- + +## 二、项目目录结构 + +``` +one-api/ +├── main.go # 程序入口 +├── router/ +│ └── relay.go # 路由定义（/v1/chat/completions 等） +├── middleware/ +│ ├── auth.go # Token 认证 +│ ├── distributor.go # 渠道分发（负载均衡） +│ └── rate-limit.go # 限流 +├── controller/ +│ └── relay.go # 入口控制器（含重试逻辑） +├── relay/ # ★ 转换层核心目录 +│ ├── adaptor.go # Adaptor 工厂函数 (69行) +│ ├── adaptor/ # 各厂商 Adaptor 实现 +│ │ ├── interface.go # Adaptor 接口定义 (9方法) +│ │ ├── common.go # 公共辅助函数 +│ │ ├── openai/ # OpenAI 适配器（基座） +│ │ ├── anthropic/ # Anthropic Claude 适配器 +│ │ ├── gemini/ # Google Gemini 适配器 +│ │ ├── geminiv2/ # Gemini V2 模型适配器 +│ │ ├── ali/ # 阿里通义千问适配器 +│ │ ├── baidu/ # 百度文心适配器 +│ │ ├── zhipu/ # 智谱 ChatGLM 适配器 +│ │ ├── tencent/ # 腾讯混元适配器 +│ │ ├── xunfei/ # 讯飞星火适配器 +│ │ ├── aws/ # AWS Bedrock Claude 适配器 (含子适配器) +│ │ │ ├── claude/ # Claude on Bedrock +│ │ │ └── llama3/ # Llama3 on Bedrock +│ │ ├── vertexai/ # Google Vertex AI (含子适配器) +│ │ │ ├── claude/ # Claude on Vertex AI +│ │ │ └── gemini/ # Gemini on Vertex AI +│ │ ├── ollama/ # Ollama 适配器 +│ │ ├── coze/ # Coze 适配器 +│ │ ├── cohere/ # Cohere 适配器 +│ │ ├── cloudflare/ # Cloudflare Workers AI 适配器 +│ │ ├── deepl/ # DeepL 翻译适配器 +│ │ ├── replicate/ # Replicate 适配器 +│ │ ├── palm/ # Google PaLM 适配器 +│ │ ├── proxy/ # 通用代理适配器 +│ │ ├── aiproxy/ # AIProxy 适配器 +│ │ └── ... (38个子目录) +│ ├── controller/ # 中转控制器（按功能分类） +│ │ ├── text.go # 文本类请求处理 (115行) +│ │ ├── image.go # 图片生成请求处理 (238行) +│ │ ├── audio.go # 音频请求处理 (281行) +│ │ ├── proxy.go # 通用代理请求处理 +│ │ ├── helper.go # 辅助函数（配额、计费等） +│ │ └── error.go # 统一错误处理 +│ ├── meta/ +│ │ └── relay_meta.go # 请求元数据结构 (66行) +│ ├── model/ # 内部数据模型 +│ │ ├── general.go # 统一 OpenAI 请求结构 (88行) +│ │ ├── message.go # 消息结构（支持多模态） (91行) +│ │ ├── misc.go # Usage、Error 等通用结构 (27行) +│ │ ├── tool.go # Tool/Function Calling 结构 +│ │ └── image.go # 图片请求结构 +│ ├── apitype/ +│ │ └── define.go # API 类型枚举 (19种) +│ ├── channeltype/ +│ │ ├── define.go # 渠道类型枚举 (56种) +│ │ ├── helper.go # ChannelType → APIType 映射 +│ │ └── url.go # 各渠道默认 BaseURL (52条) +│ ├── relaymode/ +│ │ ├── define.go # 中转模式枚举 (11种) +│ │ └── helper.go # URL 路径 → 中转模式映射 +│ └── billing/ # 计费相关 +└── model/ # 数据库模型 + ├── channel.go # 渠道配置 + └── ... +``` + +--- + +## 三、转换层技术架构 + +### 3.1 整体架构图 + +``` + ┌─────────────────────────────────────────┐ + │ 用户请求 (OpenAI 格式) │ + │ POST /v1/chat/completions │ + └──────────────────┬──────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ router/relay.go │ + │ 路由: /v1/* → controller.Relay │ + └──────────────────┬──────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ middleware (中间件链) │ + │ CORS → GzipDecode → PanicRecover │ + │ → TokenAuth → Distribute │ + │ 1. 解析 Token, 验证身份 │ + │ 2. 根据模型名选择渠道(随机负载均衡) │ + │ 3. 将渠道信息注入 gin.Context │ + └──────────────────┬──────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ controller/relay.go │ + │ 1. 根据 URL 判断 relayMode │ + │ 2. 调用 relayHelper 分发 │ + │ 3. 失败时自动重试(切换渠道) │ + └──────────────────┬──────────────────────┘ + │ + ┌────────────────────────┼────────────────────────┐ + │ │ │ + ┌─────────▼──────────┐ ┌─────────▼──────────┐ ┌─────────▼──────────┐ + │ RelayTextHelper │ │ RelayImageHelper │ │ RelayAudioHelper │ + │ text.go (115行) │ │ image.go (238行) │ │ audio.go (281行) │ + └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘ + │ │ │ + └────────────────────────┼────────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ relay/adaptor.go │ + │ GetAdaptor(apiType) → 具体Adaptor实例 │ + └──────────────────┬──────────────────────┘ + │ + ┌────────────────────────┼────────────────────────┐ + │ │ │ + ┌─────────▼──────────┐ ┌─────────▼──────────┐ ┌─────────▼──────────┐ + │ openai.Adaptor │ │ anthropic.Adaptor │ │ gemini.Adaptor │ + │ ConvertRequest() │ │ ConvertRequest() │ │ ConvertRequest() │ + │ DoRequest() │ │ DoRequest() │ │ DoRequest() │ + │ DoResponse() │ │ DoResponse() │ │ DoResponse() │ + └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘ + │ │ │ + └────────────────────────┼────────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ 上游大模型厂商 API │ + └─────────────────────────────────────────┘ +``` + +### 3.2 核心设计模式：适配器模式 + +**Adaptor 接口** (`relay/adaptor/interface.go`, 21 行): + +```go +type Adaptor interface { + Init(meta *meta.Meta) // 初始化元数据 + GetRequestURL(meta *meta.Meta) (string, error) // 构建请求 URL + SetupRequestHeader(c, req, meta) error // 设置认证请求头 + ConvertRequest(c, mode, request) (any, error) // 请求体转换 (OpenAI → 厂商) + ConvertImageRequest(request) (any, error) // 图片请求转换 + DoRequest(c, meta, requestBody) (*http.Response, error) // 发送 HTTP 请求 + DoResponse(c, resp, meta) (usage, err) // 响应体转换 (厂商 → OpenAI) + GetModelList() []string // 返回支持的模型列表 + GetChannelName() string // 返回渠道名称 +} +``` + +**9 个方法**构成最精简的适配器接口，相比 New-API 的 15+ 方法接口更聚焦。 + +### 3.3 三层映射关系 + +项目通过三层映射将"渠道"与"转换逻辑"关联： + +``` +ChannelType (渠道类型) → APIType (API 类型) → Adaptor (适配器实例) + (56 种) (19 种) (18 个实现) +``` + +- **ChannelType**: 具体的厂商/服务商标识（56 种） +- **APIType**: 共享同一套转换逻辑的分组（19 种，定义在 `relay/apitype/define.go`） +- **Adaptor**: 负责具体转换逻辑的实例 + +**映射代码**: `relay/channeltype/helper.go` 的 `ToAPIType()` 函数。 + +**关键设计**: 18 种 OpenAI 兼容渠道的 APIType 被映射为 `apitype.OpenAI`，直接复用 `openai.Adaptor`，无需编写独立转换逻辑。兼容渠道列表 (`relay/adaptor/openai/compatible.go`): + +```go +var CompatibleChannels = []int{ + Azure, AI360, Moonshot, Baichuan, Minimax, Doubao, + Mistral, Groq, LingYiWanWu, StepFun, DeepSeek, TogetherAI, + Novita, SiliconFlow, XAI, BaiduV2, XunfeiV2, +} +``` + +另有 OpenRouter、AliBailian、GeminiOpenAICompatible 也有特殊映射处理。 + +### 3.4 Adaptor 工厂 + +**文件**: `relay/adaptor.go` (69 行) + +`GetAdaptor(apiType int)` 映射 18 种 API 类型到具体适配器实例（Proxy 类型额外处理）。 + +--- + +## 四、请求处理完整流程 + +### 4.1 路由阶段 + +**文件**: `router/relay.go` (74 行) + +所有 `/v1/` 下的请求都经过中间件链：`CORS() → GzipDecodeMiddleware() → RelayPanicRecover → TokenAuth → Distribute` + +### 4.2 中间件阶段 + +#### Token 认证 (middleware/auth.go, 167 行) +- 从 `Authorization` 头提取 `Bearer ` +- 管理员可通过 `sk--` 指定特定渠道 +- 验证 Token 有效性，提取 userId、tokenId +- 从请求体解析 `model` 字段，验证模型可用性 +- 支持 IP 子网限制 + +#### 渠道分发 (middleware/distributor.go, 102 行) +- 获取用户分组 (group) +- 根据 group + model 随机选择一个可用渠道 +- 将渠道信息注入 `gin.Context`：渠道类型、API Key、BaseURL、ModelMapping 等 +- 渠道类型转换为 APIType，存入 meta + +### 4.3 控制器阶段 + +**文件**: `controller/relay.go` (156 行) + +```go +func Relay(c *gin.Context) { + relayMode := relaymode.GetByPath(c.Request.URL.Path) + bizErr := relayHelper(c, relayMode) + // 失败时自动重试：切换到其他渠道 + for i := retryTimes; i > 0; i-- { + channel := CacheGetRandomSatisfiedChannel(group, model) + SetupContextForSelectedChannel(c, channel, model) + bizErr = relayHelper(c, relayMode) + } +} +``` + +`relayHelper` 根据 `relayMode` 分发： +- `ChatCompletions / Completions / Embeddings / Moderations` → `RelayTextHelper` +- `ImagesGenerations` → `RelayImageHelper` +- `AudioSpeech / AudioTranscription / AudioTranslation` → `RelayAudioHelper` +- `Proxy` → `RelayProxyHelper` + +**重试策略**: 429 和 5xx 触发重试，400 和 2xx 不重试。管理员指定渠道时不重试。 + +### 4.4 转换处理阶段 — RelayTextHelper + +**文件**: `relay/controller/text.go` (115 行) + +```go +func RelayTextHelper(c *gin.Context) *model.ErrorWithStatusCode { + // 1. 解析请求（统一按 OpenAI 格式解析） + meta := meta.GetByContext(c) + textRequest := getAndValidateTextRequest(c, meta.Mode) + + // 2. 模型名称映射 + textRequest.Model = getMappedModelName(textRequest.Model, meta.ModelMapping) + + // 3. 强制系统提示词注入 + setSystemPrompt(textRequest, meta) + + // 4. 计算配额、预扣费 + promptTokens := getPromptTokens(textRequest, meta.Mode) + preConsumedQuota := preConsumeQuota(...) // 用户配额 > 100x预扣时跳过 + + // 5. 获取对应 Adaptor + adaptor := relay.GetAdaptor(meta.APIType) + adaptor.Init(meta) + + // 6. 请求转换（OpenAI 格式 → 厂商格式） + requestBody := getRequestBody(c, meta, textRequest, adaptor) + + // 7. 发送请求到上游 + resp := adaptor.DoRequest(c, meta, requestBody) + + // 8. 响应转换（厂商格式 → OpenAI 格式） + usage := adaptor.DoResponse(c, resp, meta) + + // 9. 后扣费 + postConsumeQuota(usage, ...) +} +``` + +#### 请求体透传优化 + +**文件**: `relay/controller/text.go` 的 `getRequestBody()` 函数 + +当满足以下所有条件时，**跳过请求转换**，直接透传原始请求体： +- API 类型为 OpenAI +- 模型名未被映射 +- 渠道不是百川（百川有特殊处理） +- 无强制系统提示词 +- 未启用 include_usage 强制选项 + +```go +if meta.APIType == apitype.OpenAI && + meta.OriginModelName == meta.ActualModelName && + meta.ChannelType != channeltype.Baichuan && + meta.ForcedSystemPrompt == "" { + return c.Request.Body, nil // 直接透传，零开销 +} +``` + +--- + +## 五、各厂商转换逻辑详解 + +### 5.1 OpenAI 适配器（基座） + +**文件**: `relay/adaptor/openai/` (9 文件) + +作为项目的"基座适配器"，不仅处理 OpenAI 自身，还被 18 种 OpenAI 兼容渠道复用。 + +**请求转换**: 基本不需要格式转换，直接透传 `GeneralOpenAIRequest`。唯一处理：流式模式下自动注入 `stream_options.include_usage = true`。 + +**URL 构建**: 根据渠道类型有不同逻辑： +- 标准 OpenAI 兼容: `BaseURL + RequestURLPath` +- Azure: `/openai/deployments/{model}/{task}?api-version=xxx` +- Minimax/Doubao/Novita/BaiduV2/AliBailian/GeminiOpenAICompatible: 各有独立 URL 逻辑 + +**认证方式**: +- 标准渠道: `Authorization: Bearer ` +- Azure: `api-key: ` +- OpenRouter: 额外 `HTTP-Referer` 和 `X-Title` 头 + +**流式处理**: 逐行解析 SSE (`data: {...}`)，提取 usage 信息，支持 Cloudflare AI Gateway URL。 + +### 5.2 Anthropic Claude 适配器 + +**文件**: `relay/adaptor/anthropic/` (4 文件, main.go 379 行) + +Claude 使用完全不同的 API 格式，需要大量转换工作。 + +**请求转换** (main.go `ConvertRequest()`): + +| OpenAI 字段 | Claude 字段 | 转换说明 | +|---|---|---| +| `messages[].role = "system"` | `system` (顶层字段) | 系统提示词提取到顶层 | +| `messages[].content` (string) | `messages[].content` (Content 数组) | 包装为 `[{type:"text", text:"..."}]` | +| `messages[].role = "tool"` | `messages[].role = "user"` + `type = "tool_result"` | 工具结果转为用户消息 | +| `messages[].tool_calls` | `content.type = "tool_use"` | 工具调用转为 content 块 | +| `tools[].function.parameters` | `tools[].input_schema` | 字段名转换 | +| `tool_choice` | `tool_choice.type + name` | auto/tool/any 格式映射 | +| `max_tokens` | `max_tokens` | 直接映射，默认 4096 | + +**认证**: `x-api-key: ` + `anthropic-version: 2023-06-01`。Claude 3.5 Sonnet 额外添加 `anthropic-beta: max-tokens-3-5-sonnet-2024-07-15`。 + +**URL**: `{base_url}/v1/messages` + +**响应转换**: + +| Claude 字段 | OpenAI 字段 | +|---|---| +| `content[].text` | `choices[].message.content` | +| `content[].type = "tool_use"` | `choices[].message.tool_calls[]` | +| `stop_reason: "end_turn"/"stop_sequence"` | `finish_reason: "stop"` | +| `stop_reason: "max_tokens"` | `finish_reason: "length"` | +| `stop_reason: "tool_use"` | `finish_reason: "tool_calls"` | +| `usage.input_tokens/output_tokens` | `usage.prompt_tokens/completion_tokens` | + +**流式处理**: Claude 的 SSE 事件类型（`message_start`、`content_block_start`、`content_block_delta`、`message_delta`）逐事件转换为 OpenAI 的 `chat.completion.chunk` 格式。 + +### 5.3 Google Gemini 适配器 + +**文件**: `relay/adaptor/gemini/` (4 文件, main.go 437 行) + +**请求转换**: + +| OpenAI 字段 | Gemini 字段 | 转换说明 | +|---|---|---| +| `messages[]` | `contents[]` | 数组结构转换 | +| `role = "assistant"` | `role = "model"` | 角色名映射 | +| `role = "system"` | `systemInstruction` 或 `role = "user"` | 新模型用 systemInstruction，旧模型转 user | +| `tools[].function` | `tools[].functionDeclarations[]` | 字段名转换 | +| `temperature/top_p/max_tokens` | `generationConfig.{temperature, topP, maxOutputTokens}` | 包装到 generationConfig | +| `response_format.type = "json_object"` | `responseMimeType = "application/json"` | MIME 类型映射 | + +**特殊处理**: +- system 消息后自动插入 `model: "Okay"` 虚拟消息（Gemini API 要求角色交替） +- 安全设置设为最低 (`GeminiSafetySetting`，5 个类别) +- 图片数量限制最多 16 张，转为 base64 inlineData +- 支持 system instruction 的模型列表硬编码: `gemini-2.0-flash`, `gemini-2.0-flash-exp`, `gemini-2.0-flash-thinking-exp-01-21` + +**URL**: `{base_url}/{version}/models/{model}:{action}` +- 版本选择: `gemini-2.0` 和 `gemini-1.5` 用 `v1beta`；其他用 `config.GeminiVersion` +- 非流式: `generateContent` +- 流式: `streamGenerateContent?alt=sse` +- Embedding: `batchEmbedContents` + +**认证**: `x-goog-api-key: ` + +### 5.4 阿里通义千问适配器 + +**文件**: `relay/adaptor/ali/` (5 文件, main.go 267 行) + +使用阿里 DashScope API 格式。 + +**请求转换**: +- Messages 包装到 `Input.Messages`，参数包装到 `Parameters`（含 `ResultFormat: "message"`, `IncrementalOutput`, `EnableSearch`） +- 模型名后缀 `-internet` 启用联网搜索 (`EnableSearch: true`) +- `top_p` 上限为 0.9999 +- 图片生成使用异步模式 (`X-DashScope-Async: enable`)，轮询等待（最多 20 步，2 秒间隔） + +**URL**: +- 文本: `/api/v1/services/aigc/text-generation/generation` +- Embedding: `/api/v1/services/embeddings/text-embedding/text-embedding` +- 图片: `/api/v1/services/aigc/text2image/image-synthesis` + +**特殊头**: `X-DashScope-SSE: enable` (流式), `X-DashScope-Async: enable` (异步) + +### 5.5 百度文心一言适配器 + +**文件**: `relay/adaptor/baidu/` (4 文件, main.go 312 行) + +**认证方式**: 百度不使用 API Key 直接认证，而是先通过 `client_id|client_secret` 获取 `access_token`，然后在 URL 中传递。 + +**access_token 缓存机制**: +- `baiduTokenStore` 使用 `sync.Map` 存储 +- 缓存的 token 在过期前 1 小时触发异步刷新 +- API Key 格式: `client_id|client_secret`，通过 OAuth2 端点获取 token + +**请求转换**: 系统消息提取到 `System` 字段，`FrequencyPenalty` → `PenaltyScore` + +**URL**: `{base_url}/rpc/2.0/ai_custom/v1/wenxinworkshop/{suffix}?access_token={token}` +- URL 中包含模型端点名称（如 `chat/completions_pro`），通过大量 switch-case 映射模型名到端点 + +### 5.6 智谱 ChatGLM 适配器 + +**文件**: `relay/adaptor/zhipu/` (4 文件) + +**双版本支持**: +- **v4** (`glm-*` 模型): `/api/paas/v4/chat/completions` — **OpenAI 兼容**，直接复用 OpenAI 的 StreamHandler/Handler +- **v3**: `/api/paas/v3/model-api/{model}/{method}` — 自有格式 + +**认证**: JWT token（API Key 格式 `id.secret`，HMAC-SHA256 签名） + +### 5.7 腾讯混元适配器 + +**文件**: `relay/adaptor/tencent/` (4 文件, main.go 307 行) + +- URL: `{baseURL}/` (单一端点) +- 认证: **TC3-HMAC-SHA256** 签名算法（完整实现在 main.go 中） +- API Key 格式: `appId|secretId|secretKey` + +### 5.8 讯飞星火适配器 + +**文件**: `relay/adaptor/xunfei/` (5 文件, main.go 273 行) + +- **协议**: WebSocket（唯一非 HTTP 适配器） +- `GetRequestURL()` 返回空字符串，`DoRequest()` 返回 dummy 200 +- `DoResponse()` 处理实际 WebSocket 通信 +- 认证: HMAC-SHA256 签名的 WebSocket URL +- API Key 格式: `appId|apiSecret|apiKey` (pipe 分隔三部分) +- 流式: 使用 `c.Stream()` + SSE 格式 +- 非流式: 累积所有 WebSocket chunk 后返回单次响应 + +### 5.9 AWS Bedrock Claude 适配器 + +**文件**: `relay/adaptor/aws/` (5 文件) + +- 使用 **AWS SDK v2** `bedrockruntime.Client`，不走 HTTP +- **子适配器模式**: `registry.go` 根据模型名分派到 `aws/claude/` 或 `aws/llama3/` +- `aws/claude/`: 复用 `anthropic.ConvertRequest()` 转换请求，使用 Bedrock `InvokeModel`/`InvokeModelWithResponseStream` 通信 +- `aws/llama3/`: Llama3 专用转换 + +### 5.10 Google Vertex AI 适配器 + +**文件**: `relay/adaptor/vertexai/` (5 文件) + +- URL: `{baseURL}/v1/projects/{project}/locations/{region}/publishers/google/models/{model}:{action}` +- Claude: `rawPredict`/`streamRawPredict?alt=sse` +- Gemini: `generateContent`/`streamGenerateContent?alt=sse` +- **子适配器模式**: `registry.go` 分派到 `vertexai/claude/` 或 `vertexai/gemini/` +- `vertexai/claude/`: 复用 `anthropic.ConvertRequest()`，设置 `anthropic_version: "vertex-2023-10-16"` +- `vertexai/gemini/`: 复用 `gemini.ConvertRequest()` +- 认证: Google Cloud IAM `GenerateAccessToken` (ADC)，Token 缓存 50 分钟 TTL + +### 5.11 其他适配器简述 + +| 适配器 | 文件 | 关键特征 | +|-------|------|---------| +| **Ollama** | `adaptor/ollama/` | 类 OpenAI 格式，`/api/chat` 或 `/api/generate` | +| **Coze** | `adaptor/coze/` | 字节跳动 Coze 平台 | +| **Cohere** | `adaptor/cohere/` | Cohere 自有 API 格式 | +| **Cloudflare** | `adaptor/cloudflare/` | Workers AI，URL 支持 Cloudflare AI Gateway | +| **DeepL** | `adaptor/deepl/` | 翻译 API，非 LLM | +| **Replicate** | `adaptor/replicate/` | 异步任务模式 | +| **PaLM** | `adaptor/palm/` | Google PaLM (旧版) | +| **Proxy** | `adaptor/proxy/` | 通用透传代理，无转换 | + +--- + +## 六、统一数据模型 + +### 6.1 统一请求模型 (`relay/model/general.go`, 88 行) + +```go +type GeneralOpenAIRequest struct { + Messages []Message // 聊天消息 + Model string // 模型名 + MaxTokens int // 最大生成 token + MaxCompletionTokens int // 最大完成 token (o-series) + Temperature *float64 // 温度 + TopP *float64 // Top-P + TopK int // Top-K + Stream bool // 流式 + StreamOptions *StreamOptions // 流式选项 + Tools []Tool // 工具调用 + ToolChoice any // 工具选择 + Stop any // 停止词 + ResponseFormat *ResponseFormat // 响应格式 + ReasoningEffort string // 推理强度 + Store *bool // 存储标记 + // ... 更多字段 +} +``` + +这是整个项目的"通用语言"——所有厂商的请求都先解析为此格式，再由各 Adaptor 转换为厂商格式。 + +### 6.2 统一消息模型 (`relay/model/message.go`, 91 行) + +```go +type Message struct { + Role string // system / user / assistant / tool / developer + Content any // 字符串 或 多模态内容数组 + ReasoningContent any // 推理内容 (o1 等模型) + Name *string // 消息发送者名称 + ToolCalls []Tool // 工具调用结果 + ToolCallId string // 工具调用 ID +} +``` + +`Content` 支持字符串（纯文本）和数组（多模态：text + image_url），通过 `ParseContent()` 解析。 + +### 6.3 统一 Usage 模型 + +```go +type Usage struct { + PromptTokens int + CompletionTokens int + TotalTokens int +} +``` + +### 6.4 统一错误模型 + +所有上游错误统一转换为 OpenAI 错误格式： +```json +{"error": {"message": "...", "type": "...", "param": "...", "code": "..."}} +``` + +`GeneralErrorResponse` 兼容多种厂商的错误格式（OpenAI 的 `error.message`、通用的 `message`、百度的 `error_msg` 等）。 + +--- + +## 七、中转模式 (RelayMode) + +**文件**: `relay/relaymode/` (2 文件) + +11 种中转模式，根据 URL 路径自动判断： + +| 模式 | URL 路径 | 说明 | +|------|---------|------| +| ChatCompletions | `/v1/chat/completions` | Chat 聊天补全 | +| Completions | `/v1/completions` | 文本补全 | +| Embeddings | `/v1/embeddings`, `/v1/engines/:model/embeddings` | 文本嵌入 | +| Moderations | `/v1/moderations` | 内容审核 | +| ImagesGenerations | `/v1/images/generations` | 图片生成 | +| Edits | `/v1/edits` | 文本编辑 | +| AudioSpeech | `/v1/audio/speech` | 语音合成 | +| AudioTranscription | `/v1/audio/transcriptions` | 语音识别 | +| AudioTranslation | `/v1/audio/translations` | 语音翻译 | +| Proxy | `/v1/oneapi/proxy/:channelid/*target` | 通用代理 | + +判断逻辑通过 `strings.HasPrefix` 匹配。 + +--- + +## 八、关键业务逻辑 + +### 8.1 配额管理 + +"预扣费 + 后结算"机制： +1. **预扣费**: 根据 prompt tokens 和模型倍率预先扣除估算配额 +2. **后结算**: 根据 usage 的实际 token 数计算费用并调整 +3. 信任优化: 用户配额超过预扣费 100 倍时跳过预扣 + +### 8.2 自动重试 + +请求失败时 (429/5xx)： +1. 选择另一个不同的渠道（随机负载均衡） +2. 重新设置上下文 +3. 从缓存的原始 body 重放请求 +4. 最多重试 `RetryTimes` 次 +5. 429 返回特殊消息"当前分组上游负载已饱和，请稍后再试" + +### 8.3 错误监控 + +`processChannelRelayError()` 异步记录错误，并通过 `monitor.ShouldDisableChannel()` 自动禁用频繁出错的渠道。 + +--- + +## 九、流式 (SSE) 处理架构 + +### 9.1 统一处理流程 + +``` +上游 SSE 流 → Scanner 逐行扫描 → 解析厂商 JSON → 转换为 OpenAI 格式 → SSE 写回客户端 +``` + +### 9.2 各厂商 SSE 格式对比 + +| 厂商 | SSE 前缀 | 数据格式 | 结束标记 | +|------|---------|---------|---------| +| OpenAI | `data: ` | `ChatCompletionsStreamResponse` | `data: [DONE]` | +| Anthropic | `data:` | `StreamResponse` (type 字段区分事件) | 无显式标记 | +| Gemini | `data: ` | `ChatResponse` | 无显式标记 | +| 阿里 | `data:` | `ChatResponse` (`\n` 分隔) | 无显式标记 | +| 百度 | `data: ` | `ChatStreamResponse` | `is_end = true` | + +### 9.3 OpenAI 兼容渠道的 SSE 优化 + +OpenAI 兼容渠道的流式数据直接透传给客户端，仅需解析统计 usage 信息，不需要格式转换。 + +--- + +## 十、架构总结 + +### 10.1 核心设计原则 + +1. **统一入口，适配器分发**: 所有请求通过同一入口，由工厂模式创建对应适配器 +2. **OpenAI 格式为"通用语言"**: 内部所有流转使用 OpenAI 格式，仅在"进出"时转换 +3. **接口抽象**: 通过 `Adaptor` 接口 (9 方法) 隔离各厂商差异，新增厂商只需实现接口 +4. **零拷贝优化**: OpenAI 兼容渠道无特殊处理时直接透传请求体 +5. **关注点分离**: 认证、分发、转换、计费、重试各自独立 + +### 10.2 新增厂商适配步骤 + +1. 在 `relay/channeltype/define.go` 添加 `ChannelType` 常量 +2. 在 `relay/apitype/define.go` 添加 `APIType`（或复用已有） +3. 在 `relay/channeltype/helper.go` 添加 `ToAPIType()` 映射 +4. 在 `relay/channeltype/url.go` 添加默认 BaseURL +5. 创建 `relay/adaptor//` 目录实现 `Adaptor` 接口 +6. 如果复用 OpenAI 格式，只需在 `compatible.go` 的 `CompatibleChannels` 列表中添加 + +### 10.3 架构特点 + +**优点**: +- 接口精简（9 方法），扩展性强 +- 18 种 OpenAI 兼容渠道零开销透传 +- 自动重试 + 渠道切换 + 错误监控自动禁用 +- 统一的计费和错误处理 +- 子适配器模式支持 Bedrock/Vertex AI 的多云厂商模型 + +**局限**: +- 仅支持 OpenAI 格式输入/输出（New-API 已在此基础上扩展了 Claude/Gemini 输入） +- 音频处理未完全走 Adaptor 接口 +- 部分适配器 SSE 解析逻辑有重复模式，可抽取公共基类 +- 缺少请求/响应中间件钩子的统一注入点 diff --git a/docs/api_reference/anthropic/count_tokens.md b/docs/api_reference/anthropic/count_tokens.md new file mode 100644 index 0000000..093edcc --- /dev/null +++ b/docs/api_reference/anthropic/count_tokens.md @@ -0,0 +1,3778 @@ +## Count Tokens + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Body Parameters + +- `messages: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + + - `content: string or array of ContentBlockParam` + + - `UnionMember0 = string` + + - `UnionMember1 = array of ContentBlockParam` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `DocumentBlockParam = object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `SearchResultBlockParam = object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `"search_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `ThinkingBlockParam = object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `"thinking"` + + - `RedactedThinkingBlockParam = object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `"redacted_thinking"` + + - `ToolUseBlockParam = object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `"tool_use"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `ToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `"tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `UnionMember0 = string` + + - `UnionMember1 = array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `SearchResultBlockParam = object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `"search_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `DocumentBlockParam = object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `ToolReferenceBlockParam = object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `ServerToolUseBlockParam = object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `"server_tool_use"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `WebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` + + - `content: WebSearchToolResultBlockParamContent` + + - `WebSearchToolResultBlockItem = array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `"web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `WebSearchToolRequestError = object { error_code, type }` + + - `error_code: WebSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `"web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `"web_search_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `WebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `WebFetchToolResultErrorBlockParam = object { error_code, type }` + + - `error_code: WebFetchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `"web_fetch_tool_result_error"` + + - `WebFetchBlockParam = object { content, type, url, retrieved_at }` + + - `content: DocumentBlockParam` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `"web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `"web_fetch_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `CodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultBlockParamContent` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `CodeExecutionToolResultErrorParam = object { error_code, type }` + + - `error_code: CodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `"code_execution_tool_result_error"` + + - `CodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `"code_execution_result"` + + - `EncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `"encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `"code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `BashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `BashCodeExecutionToolResultErrorParam = object { error_code, type }` + + - `error_code: BashCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `"bash_code_execution_tool_result_error"` + + - `BashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `"bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `"bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `"bash_code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `TextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `TextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` + + - `error_code: TextEditorCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `"text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `TextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `"text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `TextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `"text_editor_code_execution_create_result"` + + - `TextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `"text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `"text_editor_code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `ToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `ToolSearchToolResultErrorParam = object { error_code, type }` + + - `error_code: ToolSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `"tool_search_tool_result_error"` + + - `ToolSearchToolSearchResultBlockParam = object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `"tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `"tool_search_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `ContainerUploadBlockParam = object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `"container_upload"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +- `model: Model` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `UnionMember1 = string` + +- `cache_control: optional CacheControlEphemeral` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +- `output_config: optional OutputConfig` + + Configuration options for the model's output, such as the output format. + + - `effort: optional "low" or "medium" or "high" or 2 more` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `format: optional JSONOutputFormat` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + + - `"json_schema"` + +- `system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + + - `UnionMember0 = string` + + - `UnionMember1 = array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + +- `thinking: optional ThinkingConfigParam` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `ThinkingConfigEnabled = object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `"enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `ThinkingConfigDisabled = object { type }` + + - `type: "disabled"` + + - `"disabled"` + + - `ThinkingConfigAdaptive = object { type, display }` + + - `type: "adaptive"` + + - `"adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +- `tool_choice: optional ToolChoice` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `ToolChoiceAuto = object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `"auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `ToolChoiceAny = object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `"any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `ToolChoiceTool = object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `"tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `ToolChoiceNone = object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + + - `"none"` + +- `tools: optional array of MessageCountTokensTool` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + + - `Tool = object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `"object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `ToolBash20250124 = object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"bash"` + + - `type: "bash_20250124"` + + - `"bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20250522"` + + - `"code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `MemoryTool20250818 = object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"memory"` + + - `type: "memory_20250818"` + + - `"memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_editor"` + + - `type: "text_editor_20250124"` + + - `"text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_based_edit_tool"` + + - `type: "text_editor_20250429"` + + - `"text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_based_edit_tool"` + + - `type: "text_editor_20250728"` + + - `"text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_search"` + + - `type: "web_search_20250305"` + + - `"web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional UserLocation` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `"approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `WebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20250910"` + + - `"web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_search"` + + - `type: "web_search_20260209"` + + - `"web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional UserLocation` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `"approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `WebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20260209"` + + - `"web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebFetchTool20260309 = object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20260309"` + + - `"web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `ToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"tool_search_tool_bm25"` + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"tool_search_tool_regex"` + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Returns + +- `MessageTokensCount = object { input_tokens }` + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Example + +```http +curl https://api.anthropic.com/v1/messages/count_tokens \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + -d '{ + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-opus-4-6" + }' +``` diff --git a/docs/api_reference/anthropic/messages.md b/docs/api_reference/anthropic/messages.md new file mode 100644 index 0000000..b0c9a5f --- /dev/null +++ b/docs/api_reference/anthropic/messages.md @@ -0,0 +1,4774 @@ +## Create + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Body Parameters + +- `max_tokens: number` + + The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `messages: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + + - `content: string or array of ContentBlockParam` + + - `UnionMember0 = string` + + - `UnionMember1 = array of ContentBlockParam` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `DocumentBlockParam = object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `SearchResultBlockParam = object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `"search_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `ThinkingBlockParam = object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `"thinking"` + + - `RedactedThinkingBlockParam = object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `"redacted_thinking"` + + - `ToolUseBlockParam = object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `"tool_use"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `ToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `"tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `UnionMember0 = string` + + - `UnionMember1 = array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `SearchResultBlockParam = object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `"search_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `DocumentBlockParam = object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `ToolReferenceBlockParam = object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `ServerToolUseBlockParam = object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `"server_tool_use"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `WebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` + + - `content: WebSearchToolResultBlockParamContent` + + - `WebSearchToolResultBlockItem = array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `"web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `WebSearchToolRequestError = object { error_code, type }` + + - `error_code: WebSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `"web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `"web_search_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `WebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `WebFetchToolResultErrorBlockParam = object { error_code, type }` + + - `error_code: WebFetchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `"web_fetch_tool_result_error"` + + - `WebFetchBlockParam = object { content, type, url, retrieved_at }` + + - `content: DocumentBlockParam` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `ContentBlockSource = object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `UnionMember0 = string` + + - `ContentBlockSourceContent = array of ContentBlockSourceContent` + + - `TextBlockParam = object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `ImageBlockParam = object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `Base64ImageSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `"base64"` + + - `URLImageSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "image"` + + - `"image"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `"content"` + + - `URLPDFSource = object { type, url }` + + - `type: "url"` + + - `"url"` + + - `url: string` + + - `type: "document"` + + - `"document"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `"web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `"web_fetch_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `CodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultBlockParamContent` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `CodeExecutionToolResultErrorParam = object { error_code, type }` + + - `error_code: CodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `"code_execution_tool_result_error"` + + - `CodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `"code_execution_result"` + + - `EncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `"encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `"code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `BashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `BashCodeExecutionToolResultErrorParam = object { error_code, type }` + + - `error_code: BashCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `"bash_code_execution_tool_result_error"` + + - `BashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `"bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `"bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `"bash_code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `TextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `TextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` + + - `error_code: TextEditorCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `"text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `TextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `"text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `TextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `"text_editor_code_execution_create_result"` + + - `TextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `"text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `"text_editor_code_execution_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `ToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `ToolSearchToolResultErrorParam = object { error_code, type }` + + - `error_code: ToolSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `"tool_search_tool_result_error"` + + - `ToolSearchToolSearchResultBlockParam = object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `"tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `"tool_search_tool_result"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `ContainerUploadBlockParam = object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `"container_upload"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +- `model: Model` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `UnionMember1 = string` + +- `cache_control: optional CacheControlEphemeral` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +- `container: optional string` + + Container identifier for reuse across requests. + +- `inference_geo: optional string` + + Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `metadata: optional Metadata` + + An object describing metadata about the request. + + - `user_id: optional string` + + An external identifier for the user who is associated with the request. + + This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + +- `output_config: optional OutputConfig` + + Configuration options for the model's output, such as the output format. + + - `effort: optional "low" or "medium" or "high" or 2 more` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `format: optional JSONOutputFormat` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + + - `"json_schema"` + +- `service_tier: optional "auto" or "standard_only"` + + Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + + - `"auto"` + + - `"standard_only"` + +- `stop_sequences: optional array of string` + + Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `stream: optional boolean` + + Whether to incrementally stream the response using server-sent events. + + See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. + +- `system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + + - `UnionMember0 = string` + + - `UnionMember1 = array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + +- `temperature: optional number` + + Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `thinking: optional ThinkingConfigParam` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `ThinkingConfigEnabled = object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `"enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `ThinkingConfigDisabled = object { type }` + + - `type: "disabled"` + + - `"disabled"` + + - `ThinkingConfigAdaptive = object { type, display }` + + - `type: "adaptive"` + + - `"adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +- `tool_choice: optional ToolChoice` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `ToolChoiceAuto = object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `"auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `ToolChoiceAny = object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `"any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `ToolChoiceTool = object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `"tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `ToolChoiceNone = object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + + - `"none"` + +- `tools: optional array of ToolUnion` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + + - `Tool = object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `"object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `ToolBash20250124 = object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"bash"` + + - `type: "bash_20250124"` + + - `"bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20250522"` + + - `"code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `CodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"code_execution"` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `MemoryTool20250818 = object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"memory"` + + - `type: "memory_20250818"` + + - `"memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_editor"` + + - `type: "text_editor_20250124"` + + - `"text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_based_edit_tool"` + + - `type: "text_editor_20250429"` + + - `"text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"str_replace_based_edit_tool"` + + - `type: "text_editor_20250728"` + + - `"text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_search"` + + - `type: "web_search_20250305"` + + - `"web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional UserLocation` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `"approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `WebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20250910"` + + - `"web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_search"` + + - `type: "web_search_20260209"` + + - `"web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional UserLocation` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `"approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `WebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20260209"` + + - `"web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `WebFetchTool20260309 = object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"web_fetch"` + + - `type: "web_fetch_20260309"` + + - `"web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional CitationsConfigParam` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `ToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"tool_search_tool_bm25"` + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `ToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `"tool_search_tool_regex"` + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional CacheControlEphemeral` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `"ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +- `top_k: optional number` + + Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `top_p: optional number` + + Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +### Returns + +- `Message = object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: Container` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `TextBlock = object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `CitationCharLocation = object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `"char_location"` + + - `CitationPageLocation = object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `"page_location"` + + - `CitationContentBlockLocation = object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `"content_block_location"` + + - `CitationsWebSearchResultLocation = object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `"web_search_result_location"` + + - `url: string` + + - `CitationsSearchResultLocation = object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `"search_result_location"` + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `ThinkingBlock = object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `"thinking"` + + - `RedactedThinkingBlock = object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `"redacted_thinking"` + + - `ToolUseBlock = object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `"tool_use"` + + - `ServerToolUseBlock = object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `"server_tool_use"` + + - `WebSearchToolResultBlock = object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `content: WebSearchToolResultBlockContent` + + - `WebSearchToolResultError = object { error_code, type }` + + - `error_code: WebSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `"web_search_tool_result_error"` + + - `UnionMember1 = array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `"web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `"web_search_tool_result"` + + - `WebFetchToolResultBlock = object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `DirectCaller = object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `"direct"` + + - `ServerToolCaller = object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `"code_execution_20250825"` + + - `ServerToolCaller20260120 = object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `"code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `WebFetchToolResultErrorBlock = object { error_code, type }` + + - `error_code: WebFetchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `"web_fetch_tool_result_error"` + + - `WebFetchBlock = object { content, retrieved_at, type, url }` + + - `content: DocumentBlock` + + - `citations: CitationsConfig` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `Base64PDFSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `"application/pdf"` + + - `type: "base64"` + + - `"base64"` + + - `PlainTextSource = object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `"text/plain"` + + - `type: "text"` + + - `"text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `"document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `"web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `"web_fetch_tool_result"` + + - `CodeExecutionToolResultBlock = object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultBlockContent` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `CodeExecutionToolResultError = object { error_code, type }` + + - `error_code: CodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `"code_execution_tool_result_error"` + + - `CodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `"code_execution_result"` + + - `EncryptedCodeExecutionResultBlock = object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `"code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `"encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `"code_execution_tool_result"` + + - `BashCodeExecutionToolResultBlock = object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `BashCodeExecutionToolResultError = object { error_code, type }` + + - `error_code: BashCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `"bash_code_execution_tool_result_error"` + + - `BashCodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `"bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `"bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `"bash_code_execution_tool_result"` + + - `TextEditorCodeExecutionToolResultBlock = object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `TextEditorCodeExecutionToolResultError = object { error_code, error_message, type }` + + - `error_code: TextEditorCodeExecutionToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `"text_editor_code_execution_tool_result_error"` + + - `TextEditorCodeExecutionViewResultBlock = object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `"text_editor_code_execution_view_result"` + + - `TextEditorCodeExecutionCreateResultBlock = object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `"text_editor_code_execution_create_result"` + + - `TextEditorCodeExecutionStrReplaceResultBlock = object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `"text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `"text_editor_code_execution_tool_result"` + + - `ToolSearchToolResultBlock = object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `ToolSearchToolResultError = object { error_code, error_message, type }` + + - `error_code: ToolSearchToolResultErrorCode` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `"tool_search_tool_result_error"` + + - `ToolSearchToolSearchResultBlock = object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `"tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `"tool_search_tool_result"` + + - `ContainerUploadBlock = object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `"container_upload"` + + - `model: Model` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `UnionMember1 = string` + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `"assistant"` + + - `stop_details: RefusalStopDetails` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `"refusal"` + + - `stop_reason: StopReason` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `"message"` + + - `usage: Usage` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: CacheCreation` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: ServerToolUsage` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Example + +```http +curl https://api.anthropic.com/v1/messages \ + -H 'Content-Type: application/json' \ + -H 'anthropic-version: 2023-06-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" \ + --max-time 600 \ + -d '{ + "max_tokens": 1024, + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-opus-4-6" + }' +``` diff --git a/docs/api_reference/anthropic/messages_use.md b/docs/api_reference/anthropic/messages_use.md new file mode 100644 index 0000000..132475e --- /dev/null +++ b/docs/api_reference/anthropic/messages_use.md @@ -0,0 +1,1209 @@ +# Using the Messages API + +Practical patterns and examples for using the Messages API effectively + +--- + +Anthropic offers two ways to build with Claude, each suited to different use cases: + +| | Messages API | Claude Managed Agents | +|---|---|---| +| **What it is** | Direct model prompting access | Pre-built, configurable agent harness that runs in managed infrastructure | +| **Best for** | Custom agent loops and fine-grained control | Long-running tasks and asynchronous work | +| **Learn more** | [Messages API docs](/docs/en/build-with-claude/working-with-messages) | [Claude Managed Agents docs](/docs/en/managed-agents/overview) | + +This guide covers common patterns for working with the Messages API, including basic requests, multi-turn conversations, prefill techniques, and vision capabilities. For complete API specifications, see the [Messages API reference](/docs/en/api/messages/create). + + +This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. + + +## Basic request and response + + + ```bash cURL + #!/bin/sh + curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data \ + '{ + "model": "claude-opus-4-7", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": "Hello, Claude"} + ] + }' + ``` + + ```bash CLI + ant messages create \ + --model claude-opus-4-7 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' + ``` + + ```python Python hidelines={1..2} + import anthropic + + message = anthropic.Anthropic().messages.create( + model="claude-opus-4-7", + max_tokens=1024, + messages=[{"role": "user", "content": "Hello, Claude"}], + ) + print(message) + ``` + + ```typescript TypeScript hidelines={1..2} + import Anthropic from "@anthropic-ai/sdk"; + + const anthropic = new Anthropic(); + + const message = await anthropic.messages.create({ + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [{ role: "user", content: "Hello, Claude" }] + }); + console.log(message); + ``` + + ```csharp C# + using System; + using System.Threading.Tasks; + using Anthropic; + using Anthropic.Models.Messages; + + class Program + { + static async Task Main() + { + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus4_7, + MaxTokens = 1024, + Messages = [new() { Role = Role.User, Content = "Hello, Claude" }] + }; + var message = await client.Messages.Create(parameters); + Console.WriteLine(message); + } + } + ``` + + ```go Go hidelines={1..11,-1} + package main + + import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + ) + + func main() { + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_7, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response) + } + ``` + + ```java Java hidelines={1..8,-2..} + import com.anthropic.client.AnthropicClient; + import com.anthropic.client.okhttp.AnthropicOkHttpClient; + import com.anthropic.models.messages.MessageCreateParams; + import com.anthropic.models.messages.Message; + import com.anthropic.models.messages.Model; + + public class Main { + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_7) + .maxTokens(1024L) + .addUserMessage("Hello, Claude") + .build(); + + Message response = client.messages().create(params); + System.out.println(response); + } + } + ``` + + ```php PHP hidelines={1..4} + messages->create( + maxTokens: 1024, + messages: [['role' => 'user', 'content' => 'Hello, Claude']], + model: 'claude-opus-4-7', + ); + echo $message->content[0]->text; + ``` + + ```ruby Ruby hidelines={1..2} + require "anthropic" + + client = Anthropic::Client.new + + message = client.messages.create( + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [ + { role: "user", content: "Hello, Claude" } + ] + ) + puts message + ``` + + +```json Output +{ + "id": "msg_01XFDUDYJgAACzvnptvVoYEL", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Hello!" + } + ], + "model": "claude-opus-4-7", + "stop_reason": "end_turn", + "stop_sequence": null, + "usage": { + "input_tokens": 12, + "output_tokens": 6 + } +} +``` + +## Multiple conversational turns + +The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don't necessarily need to actually originate from Claude. You can use synthetic `assistant` messages. + + +```bash cURL +#!/bin/sh +curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data \ +'{ + "model": "claude-opus-4-7", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": "Hello, Claude"}, + {"role": "assistant", "content": "Hello!"}, + {"role": "user", "content": "Can you describe LLMs to me?"} + + ] +}' +``` + +```bash CLI +ant messages create \ + --model claude-opus-4-7 \ + --max-tokens 1024 \ + --message '{role: user, content: "Hello, Claude"}' \ + --message '{role: assistant, content: "Hello!"}' \ + --message '{role: user, content: "Can you describe LLMs to me?"}' +``` + +```python Python hidelines={1..2} +import anthropic + +message = anthropic.Anthropic().messages.create( + model="claude-opus-4-7", + max_tokens=1024, + messages=[ + {"role": "user", "content": "Hello, Claude"}, + {"role": "assistant", "content": "Hello!"}, + {"role": "user", "content": "Can you describe LLMs to me?"}, + ], +) +print(message) +``` + +```typescript TypeScript hidelines={1..2} +import Anthropic from "@anthropic-ai/sdk"; + +const anthropic = new Anthropic(); + +await anthropic.messages.create({ + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [ + { role: "user", content: "Hello, Claude" }, + { role: "assistant", content: "Hello!" }, + { role: "user", content: "Can you describe LLMs to me?" } + ] +}); +``` + +```csharp C# +using System; +using System.Threading.Tasks; +using Anthropic; +using Anthropic.Models.Messages; + +class Program +{ + static async Task Main(string[] args) + { + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus4_7, + MaxTokens = 1024, + Messages = + [ + new() { Role = Role.User, Content = "Hello, Claude" }, + new() { Role = Role.Assistant, Content = "Hello!" }, + new() { Role = Role.User, Content = "Can you describe LLMs to me?" } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message); + } +} +``` + +```go Go hidelines={1..11,-1} +package main + +import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" +) + +func main() { + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_7, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), + anthropic.NewAssistantMessage(anthropic.NewTextBlock("Hello!")), + anthropic.NewUserMessage(anthropic.NewTextBlock("Can you describe LLMs to me?")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response) +} +``` + +```java Java hidelines={1..8,-2..} +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Message; +import com.anthropic.models.messages.Model; + +public class MultiTurnConversation { + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_7) + .maxTokens(1024L) + .addUserMessage("Hello, Claude") + .addAssistantMessage("Hello!") + .addUserMessage("Can you describe LLMs to me?") + .build(); + + Message response = client.messages().create(params); + System.out.println(response); + } +} +``` + +```php PHP hidelines={1..4} +messages->create( + maxTokens: 1024, + messages: [ + ['role' => 'user', 'content' => 'Hello, Claude'], + ['role' => 'assistant', 'content' => 'Hello!'], + ['role' => 'user', 'content' => 'Can you describe LLMs to me?'], + ], + model: 'claude-opus-4-7', +); + +echo $message->content[0]->text; +``` + +```ruby Ruby hidelines={1..2} +require "anthropic" + +client = Anthropic::Client.new + +message = client.messages.create( + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [ + { role: "user", content: "Hello, Claude" }, + { role: "assistant", content: "Hello!" }, + { role: "user", content: "Can you describe LLMs to me?" } + ] +) +puts message +``` + + +```json Output +{ + "id": "msg_018gCsTGsXkYJVqYPxTgDHBU", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Sure, I'd be happy to provide..." + } + ], + "stop_reason": "end_turn", + "stop_sequence": null, + "usage": { + "input_tokens": 30, + "output_tokens": 309 + } +} +``` + +## Putting words in Claude's mouth + +You can pre-fill part of Claude's response in the last position of the input messages list. This can be used to shape Claude's response. The example below uses `"max_tokens": 1` to get a single multiple choice answer from Claude. + + + ```bash cURL + #!/bin/sh + curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data \ + '{ + "model": "claude-sonnet-4-5", + "max_tokens": 1, + "messages": [ + {"role": "user", "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"}, + {"role": "assistant", "content": "The answer is ("} + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-sonnet-4-5 + max_tokens: 1 + messages: + - role: user + content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" + - role: assistant + content: "The answer is (" + YAML + ``` + + ```python Python hidelines={1..2} + import anthropic + + message = anthropic.Anthropic().messages.create( + model="claude-sonnet-4-5", + max_tokens=1, + messages=[ + { + "role": "user", + "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae", + }, + {"role": "assistant", "content": "The answer is ("}, + ], + ) + print(message) + ``` + + ```typescript TypeScript hidelines={1..2} + import Anthropic from "@anthropic-ai/sdk"; + + const anthropic = new Anthropic(); + + const message = await anthropic.messages.create({ + model: "claude-sonnet-4-5", + max_tokens: 1, + messages: [ + { + role: "user", + content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" + }, + { role: "assistant", content: "The answer is (" } + ] + }); + console.log(message); + ``` + + ```csharp C# + using System; + using System.Threading.Tasks; + using Anthropic; + using Anthropic.Models.Messages; + + class Program + { + static async Task Main(string[] args) + { + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeSonnet4_5, + MaxTokens = 1, + Messages = [ + new() { Role = Role.User, Content = "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" }, + new() { Role = Role.Assistant, Content = "The answer is (" } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message); + } + } + ``` + + ```go Go hidelines={1..11,-1} + package main + + import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + ) + + func main() { + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_5, + MaxTokens: 1, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae")), + anthropic.NewAssistantMessage(anthropic.NewTextBlock("The answer is (")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response) + } + ``` + + ```java Java hidelines={1..8,-2..} + import com.anthropic.client.AnthropicClient; + import com.anthropic.client.okhttp.AnthropicOkHttpClient; + import com.anthropic.models.messages.MessageCreateParams; + import com.anthropic.models.messages.Message; + import com.anthropic.models.messages.Model; + + public class PrefillExample { + public static void main(String[] args) { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_5) + .maxTokens(1L) + .addUserMessage("What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae") + .addAssistantMessage("The answer is (") + .build(); + + Message response = client.messages().create(params); + System.out.println(response); + } + } + ``` + + ```php PHP hidelines={1..4} + messages->create( + maxTokens: 1, + messages: [ + ['role' => 'user', 'content' => 'What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae'], + ['role' => 'assistant', 'content' => 'The answer is ('], + ], + model: 'claude-sonnet-4-5', + ); + echo $message->content[0]->text; + ``` + + ```ruby Ruby hidelines={1..2} + require "anthropic" + + client = Anthropic::Client.new + + message = client.messages.create( + model: "claude-sonnet-4-5", + max_tokens: 1, + messages: [ + { + role: "user", + content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" + }, + { role: "assistant", content: "The answer is (" } + ] + ) + puts message + ``` + + +```json Output +{ + "id": "msg_01Q8Faay6S7QPTvEUUQARt7h", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "C" + } + ], + "model": "claude-sonnet-4-5", + "stop_reason": "max_tokens", + "stop_sequence": null, + "usage": { + "input_tokens": 42, + "output_tokens": 1 + } +} +``` + + +Prefilling is not supported on [Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6. Requests using prefill with these models return a 400 error. Use [structured outputs](/docs/en/build-with-claude/structured-outputs) or system prompt instructions instead. See the [migration guide](/docs/en/about-claude/models/migration-guide) for migration patterns. + + +## Vision + +Claude can read both text and images in requests. Images can be supplied using the `base64`, `url`, or `file` source types. The `file` source type references an image uploaded through the [Files API](/docs/en/build-with-claude/files). Supported media types are `image/jpeg`, `image/png`, `image/gif`, and `image/webp`. See the [vision guide](/docs/en/build-with-claude/vision) for more details. + + + ```bash cURL + #!/bin/sh + + # Option 1: Base64-encoded image + IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + IMAGE_MEDIA_TYPE="image/jpeg" + IMAGE_BASE64=$(curl "$IMAGE_URL" | base64 | tr -d '\n') + + curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data \ + '{ + "model": "claude-opus-4-7", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": [ + {"type": "image", "source": { + "type": "base64", + "media_type": "'$IMAGE_MEDIA_TYPE'", + "data": "'$IMAGE_BASE64'" + }}, + {"type": "text", "text": "What is in the above image?"} + ]} + ] + }' + + # Option 2: URL-referenced image + curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data \ + '{ + "model": "claude-opus-4-7", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": [ + {"type": "image", "source": { + "type": "url", + "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + }}, + {"type": "text", "text": "What is in the above image?"} + ]} + ] + }' + ``` + + + ```bash CLI nocheck + IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + + # Option 1: Base64-encoded image (CLI auto-encodes binary @file refs) + curl -s "$IMAGE_URL" -o ./ant.jpg + + ant messages create <<'YAML' + model: claude-opus-4-7 + max_tokens: 1024 + messages: + - role: user + content: + - type: image + source: + type: base64 + media_type: image/jpeg + data: "@./ant.jpg" + - type: text + text: What is in the above image? + YAML + + # Option 2: URL-referenced image + ant messages create < + { + new ContentBlockParam(new ImageBlockParam( + new ImageBlockParamSource(new Base64ImageSource() + { + Data = imageData, + MediaType = MediaType.ImageJpeg, + }) + )), + new ContentBlockParam(new TextBlockParam("What is in the above image?")), + }), + } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message); + + // Option 2: URL-referenced image + var parametersFromUrl = new MessageCreateParams + { + Model = Model.ClaudeOpus4_7, + MaxTokens = 1024, + Messages = + [ + new() + { + Role = Role.User, + Content = new MessageParamContent(new List + { + new ContentBlockParam(new ImageBlockParam( + new ImageBlockParamSource(new UrlImageSource() + { + Url = new Uri("https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"), + }) + )), + new ContentBlockParam(new TextBlockParam("What is in the above image?")), + }), + } + ] + }; + + var messageFromUrl = await client.Messages.Create(parametersFromUrl); + Console.WriteLine(messageFromUrl); + } + } + ``` + + + ```go Go nocheck hidelines={1..16,-1} + package main + + import ( + "context" + "encoding/base64" + "fmt" + "io" + "log" + "net/http" + + "github.com/anthropics/anthropic-sdk-go" + ) + + func main() { + client := anthropic.NewClient() + + // Option 1: Base64-encoded image + imageURL := "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + + req, err := http.NewRequest("GET", imageURL, nil) + if err != nil { + log.Fatal(err) + } + req.Header.Set("User-Agent", "AnthropicDocsBot/1.0") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + log.Fatal(err) + } + defer resp.Body.Close() + + imageBytes, err := io.ReadAll(resp.Body) + if err != nil { + log.Fatal(err) + } + imageData := base64.StdEncoding.EncodeToString(imageBytes) + + message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_7, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage( + anthropic.NewImageBlockBase64("image/jpeg", imageData), + anthropic.NewTextBlock("What is in the above image?"), + ), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(message) + + // Option 2: URL-referenced image + messageFromURL, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_7, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage( + anthropic.NewImageBlock(anthropic.URLImageSourceParam{ + URL: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg", + }), + anthropic.NewTextBlock("What is in the above image?"), + ), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(messageFromURL) + } + ``` + + + ```java Java nocheck hidelines={1..12,-2..} + import com.anthropic.client.AnthropicClient; + import com.anthropic.client.okhttp.AnthropicOkHttpClient; + import com.anthropic.models.messages.*; + import java.net.URI; + import java.net.http.HttpClient; + import java.net.http.HttpRequest; + import java.net.http.HttpResponse; + import java.util.Base64; + import java.util.List; + + public class VisionExample { + public static void main(String[] args) throws Exception { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + // Option 1: Base64-encoded image + String imageUrl = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"; + + HttpClient httpClient = HttpClient.newHttpClient(); + HttpRequest request = HttpRequest.newBuilder().uri(URI.create(imageUrl)).build(); + HttpResponse response = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray()); + String imageData = Base64.getEncoder().encodeToString(response.body()); + + List base64Content = List.of( + ContentBlockParam.ofImage( + ImageBlockParam.builder() + .source(Base64ImageSource.builder() + .data(imageData) + .mediaType(Base64ImageSource.MediaType.IMAGE_JPEG) + .build()) + .build()), + ContentBlockParam.ofText( + TextBlockParam.builder() + .text("What is in the above image?") + .build()) + ); + + Message message = client.messages().create( + MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_7) + .maxTokens(1024L) + .addUserMessageOfBlockParams(base64Content) + .build()); + System.out.println(message); + + // Option 2: URL-referenced image + List urlContent = List.of( + ContentBlockParam.ofImage( + ImageBlockParam.builder() + .source(UrlImageSource.builder() + .url("https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg") + .build()) + .build()), + ContentBlockParam.ofText( + TextBlockParam.builder() + .text("What is in the above image?") + .build()) + ); + + Message messageFromUrl = client.messages().create( + MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_7) + .maxTokens(1024L) + .addUserMessageOfBlockParams(urlContent) + .build()); + System.out.println(messageFromUrl); + } + } + ``` + + + ```php PHP hidelines={1..4} nocheck + messages->create( + maxTokens: 1024, + messages: [ + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'image', + 'source' => [ + 'type' => 'base64', + 'media_type' => $image_media_type, + 'data' => $image_data, + ], + ], + [ + 'type' => 'text', + 'text' => 'What is in the above image?', + ], + ], + ], + ], + model: 'claude-opus-4-7', + ); + echo $message; + + // Option 2: URL-referenced image + $message_from_url = $client->messages->create( + maxTokens: 1024, + messages: [ + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'image', + 'source' => [ + 'type' => 'url', + 'url' => 'https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg', + ], + ], + [ + 'type' => 'text', + 'text' => 'What is in the above image?', + ], + ], + ], + ], + model: 'claude-opus-4-7', + ); + echo $message_from_url; + ``` + + + ```ruby Ruby nocheck hidelines={1} + require "anthropic" + require "base64" + require "net/http" + + client = Anthropic::Client.new + + # Option 1: Base64-encoded image + image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + image_media_type = "image/jpeg" + image_data = Base64.strict_encode64(Net::HTTP.get(URI(image_url))) + + message = client.messages.create( + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { + type: "base64", + media_type: image_media_type, + data: image_data + } + }, + { + type: "text", + text: "What is in the above image?" + } + ] + } + ] + ) + puts message + + # Option 2: URL-referenced image + message_from_url = client.messages.create( + model: "claude-opus-4-7", + max_tokens: 1024, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { + type: "url", + url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" + } + }, + { + type: "text", + text: "What is in the above image?" + } + ] + } + ] + ) + puts message_from_url + ``` + + +```json Output +{ + "id": "msg_01EcyWo6m4hyW8KHs2y2pei5", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective." + } + ], + "model": "claude-opus-4-7", + "stop_reason": "end_turn", + "stop_sequence": null, + "usage": { + "input_tokens": 1551, + "output_tokens": 71 + } +} +``` + +## Tool use and computer use + +See the [tool use guide](/docs/en/agents-and-tools/tool-use/overview) for examples of how to use tools with the Messages API. +See the [computer use guide](/docs/en/agents-and-tools/tool-use/computer-use-tool) for examples of how to control desktop computer environments with the Messages API. +For guaranteed JSON output, see [Structured Outputs](/docs/en/build-with-claude/structured-outputs). \ No newline at end of file diff --git a/docs/api_reference/anthropic/models.md b/docs/api_reference/anthropic/models.md new file mode 100644 index 0000000..c5d04a2 --- /dev/null +++ b/docs/api_reference/anthropic/models.md @@ -0,0 +1,291 @@ +## List + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Query Parameters + +- `after_id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `before_id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 20 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + + - `"advisor-tool-2026-03-01"` + + - `"user-profiles-2026-03-24"` + +### Returns + +- `data: array of ModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: ModelCapabilities` + + Model capability information. + + - `batch: CapabilitySupport` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: CapabilitySupport` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: CapabilitySupport` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: ContextManagementCapability` + + Context management support and available strategies. + + - `clear_thinking_20251015: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: EffortCapability` + + Effort (reasoning_effort) support and available levels. + + - `high: CapabilitySupport` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: CapabilitySupport` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: CapabilitySupport` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: CapabilitySupport` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `xhigh: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: CapabilitySupport` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: CapabilitySupport` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: CapabilitySupport` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: ThinkingCapability` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: ThinkingTypes` + + Supported thinking type configurations. + + - `adaptive: CapabilitySupport` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: CapabilitySupport` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `"model"` + +- `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + +- `has_more: boolean` + + Indicates if there are more results in the requested page direction. + +- `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```http +curl https://api.anthropic.com/v1/models \ + -H 'anthropic-version: 2023-06-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/docs/api_reference/anthropic/models_get.md b/docs/api_reference/anthropic/models_get.md new file mode 100644 index 0000000..4c9a5cb --- /dev/null +++ b/docs/api_reference/anthropic/models_get.md @@ -0,0 +1,269 @@ +## Retrieve + +**get** `/v1/models/{model_id}` + +Get a specific model. + +The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. + +### Path Parameters + +- `model_id: string` + + Model identifier or alias. + +### Header Parameters + +- `"anthropic-beta": optional array of AnthropicBeta` + + Optional header to specify the beta version(s) you want to use. + + - `UnionMember0 = string` + + - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 20 more` + + - `"message-batches-2024-09-24"` + + - `"prompt-caching-2024-07-31"` + + - `"computer-use-2024-10-22"` + + - `"computer-use-2025-01-24"` + + - `"pdfs-2024-09-25"` + + - `"token-counting-2024-11-01"` + + - `"token-efficient-tools-2025-02-19"` + + - `"output-128k-2025-02-19"` + + - `"files-api-2025-04-14"` + + - `"mcp-client-2025-04-04"` + + - `"mcp-client-2025-11-20"` + + - `"dev-full-thinking-2025-05-14"` + + - `"interleaved-thinking-2025-05-14"` + + - `"code-execution-2025-05-22"` + + - `"extended-cache-ttl-2025-04-11"` + + - `"context-1m-2025-08-07"` + + - `"context-management-2025-06-27"` + + - `"model-context-window-exceeded-2025-08-26"` + + - `"skills-2025-10-02"` + + - `"fast-mode-2026-02-01"` + + - `"output-300k-2026-03-24"` + + - `"advisor-tool-2026-03-01"` + + - `"user-profiles-2026-03-24"` + +### Returns + +- `ModelInfo = object { id, capabilities, created_at, 4 more }` + + - `id: string` + + Unique model identifier. + + - `capabilities: ModelCapabilities` + + Model capability information. + + - `batch: CapabilitySupport` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: CapabilitySupport` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: CapabilitySupport` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: ContextManagementCapability` + + Context management support and available strategies. + + - `clear_thinking_20251015: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: EffortCapability` + + Effort (reasoning_effort) support and available levels. + + - `high: CapabilitySupport` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: CapabilitySupport` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: CapabilitySupport` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: CapabilitySupport` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `xhigh: CapabilitySupport` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: CapabilitySupport` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: CapabilitySupport` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: CapabilitySupport` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: ThinkingCapability` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: ThinkingTypes` + + Supported thinking type configurations. + + - `adaptive: CapabilitySupport` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: CapabilitySupport` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `"model"` + +### Example + +```http +curl https://api.anthropic.com/v1/models/$MODEL_ID \ + -H 'anthropic-version: 2023-06-01' \ + -H "X-Api-Key: $ANTHROPIC_API_KEY" +``` diff --git a/docs/api_reference/openai/chat.md b/docs/api_reference/openai/chat.md new file mode 100644 index 0000000..8d68180 --- /dev/null +++ b/docs/api_reference/openai/chat.md @@ -0,0 +1,2178 @@ +## Create chat completion + +**post** `/chat/completions` + +**Starting a new project?** We recommend trying [Responses](/docs/api-reference/responses) +to take advantage of the latest OpenAI platform features. Compare +[Chat Completions with Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses). + +--- + +Creates a model response for the given chat conversation. Learn more in the +[text generation](/docs/guides/text-generation), [vision](/docs/guides/vision), +and [audio](/docs/guides/audio) guides. + +Parameter support can differ depending on the model used to generate the +response, particularly for newer reasoning models. Parameters that are only +supported for reasoning models are noted below. For the current state of +unsupported parameters in reasoning models, +[refer to the reasoning guide](/docs/guides/reasoning). + +Returns a chat completion object, or a streamed sequence of chat completion +chunk objects if the request is streamed. + +### Body Parameters + +- `messages: array of ChatCompletionMessageParam` + + A list of messages comprising the conversation so far. Depending on the + [model](/docs/models) you use, different message types (modalities) are + supported, like [text](/docs/guides/text-generation), + [images](/docs/guides/vision), and [audio](/docs/guides/audio). + + - `ChatCompletionDeveloperMessageParam object { content, role, name }` + + Developer-provided instructions that the model should follow, regardless of + messages sent by the user. With o1 models and newer, `developer` messages + replace the previous `system` messages. + + - `content: string or array of ChatCompletionContentPartText` + + The contents of the developer message. + + - `TextContent = string` + + The contents of the developer message. + + - `ArrayOfContentParts = array of ChatCompletionContentPartText` + + An array of content parts with a defined type. For developer messages, only type `text` is supported. + + - `text: string` + + The text content. + + - `type: "text"` + + The type of the content part. + + - `"text"` + + - `role: "developer"` + + The role of the messages author, in this case `developer`. + + - `"developer"` + + - `name: optional string` + + An optional name for the participant. Provides the model information to differentiate between participants of the same role. + + - `ChatCompletionSystemMessageParam object { content, role, name }` + + Developer-provided instructions that the model should follow, regardless of + messages sent by the user. With o1 models and newer, use `developer` messages + for this purpose instead. + + - `content: string or array of ChatCompletionContentPartText` + + The contents of the system message. + + - `TextContent = string` + + The contents of the system message. + + - `ArrayOfContentParts = array of ChatCompletionContentPartText` + + An array of content parts with a defined type. For system messages, only type `text` is supported. + + - `text: string` + + The text content. + + - `type: "text"` + + The type of the content part. + + - `role: "system"` + + The role of the messages author, in this case `system`. + + - `"system"` + + - `name: optional string` + + An optional name for the participant. Provides the model information to differentiate between participants of the same role. + + - `ChatCompletionUserMessageParam object { content, role, name }` + + Messages sent by an end user, containing prompts or additional context + information. + + - `content: string or array of ChatCompletionContentPart` + + The contents of the user message. + + - `TextContent = string` + + The text contents of the message. + + - `ArrayOfContentParts = array of ChatCompletionContentPart` + + An array of content parts with a defined type. Supported options differ based on the [model](/docs/models) being used to generate the response. Can contain text, image, or audio inputs. + + - `ChatCompletionContentPartText object { text, type }` + + Learn about [text inputs](/docs/guides/text-generation). + + - `text: string` + + The text content. + + - `type: "text"` + + The type of the content part. + + - `ChatCompletionContentPartImage object { image_url, type }` + + Learn about [image inputs](/docs/guides/vision). + + - `image_url: object { url, detail }` + + - `url: string` + + Either a URL of the image or the base64 encoded image data. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. Learn more in the [Vision guide](/docs/guides/vision#low-or-high-fidelity-image-understanding). + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `"image_url"` + + - `ChatCompletionContentPartInputAudio object { input_audio, type }` + + Learn about [audio inputs](/docs/guides/audio). + + - `input_audio: object { data, format }` + + - `data: string` + + Base64 encoded audio data. + + - `format: "wav" or "mp3"` + + The format of the encoded audio data. Currently supports "wav" and "mp3". + + - `"wav"` + + - `"mp3"` + + - `type: "input_audio"` + + The type of the content part. Always `input_audio`. + + - `"input_audio"` + + - `FileContentPart object { file, type }` + + Learn about [file inputs](/docs/guides/text) for text generation. + + - `file: object { file_data, file_id, filename }` + + - `file_data: optional string` + + The base64 encoded file data, used when passing the file to the model + as a string. + + - `file_id: optional string` + + The ID of an uploaded file to use as input. + + - `filename: optional string` + + The name of the file, used when passing the file to the model as a + string. + + - `type: "file"` + + The type of the content part. Always `file`. + + - `"file"` + + - `role: "user"` + + The role of the messages author, in this case `user`. + + - `"user"` + + - `name: optional string` + + An optional name for the participant. Provides the model information to differentiate between participants of the same role. + + - `ChatCompletionAssistantMessageParam object { role, audio, content, 4 more }` + + Messages sent by the model in response to user messages. + + - `role: "assistant"` + + The role of the messages author, in this case `assistant`. + + - `"assistant"` + + - `audio: optional object { id }` + + Data about a previous audio response from the model. + [Learn more](/docs/guides/audio). + + - `id: string` + + Unique identifier for a previous audio response from the model. + + - `content: optional string or array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal` + + The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified. + + - `TextContent = string` + + The contents of the assistant message. + + - `ArrayOfContentParts = array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal` + + An array of content parts with a defined type. Can be one or more of type `text`, or exactly one of type `refusal`. + + - `ChatCompletionContentPartText object { text, type }` + + Learn about [text inputs](/docs/guides/text-generation). + + - `ChatCompletionContentPartRefusal object { refusal, type }` + + - `refusal: string` + + The refusal message generated by the model. + + - `type: "refusal"` + + The type of the content part. + + - `"refusal"` + + - `function_call: optional object { arguments, name }` + + Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. + + - `arguments: string` + + The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + + - `name: string` + + The name of the function to call. + + - `name: optional string` + + An optional name for the participant. Provides the model information to differentiate between participants of the same role. + + - `refusal: optional string` + + The refusal message by the assistant. + + - `tool_calls: optional array of ChatCompletionMessageToolCall` + + The tool calls generated by the model, such as function calls. + + - `ChatCompletionMessageFunctionToolCall object { id, function, type }` + + A call to a function tool created by the model. + + - `id: string` + + The ID of the tool call. + + - `function: object { arguments, name }` + + The function that the model called. + + - `arguments: string` + + The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + The type of the tool. Currently, only `function` is supported. + + - `"function"` + + - `ChatCompletionMessageCustomToolCall object { id, custom, type }` + + A call to a custom tool created by the model. + + - `id: string` + + The ID of the tool call. + + - `custom: object { input, name }` + + The custom tool that the model called. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + The type of the tool. Always `custom`. + + - `"custom"` + + - `ChatCompletionToolMessageParam object { content, role, tool_call_id }` + + - `content: string or array of ChatCompletionContentPartText` + + The contents of the tool message. + + - `TextContent = string` + + The contents of the tool message. + + - `ArrayOfContentParts = array of ChatCompletionContentPartText` + + An array of content parts with a defined type. For tool messages, only type `text` is supported. + + - `text: string` + + The text content. + + - `type: "text"` + + The type of the content part. + + - `role: "tool"` + + The role of the messages author, in this case `tool`. + + - `"tool"` + + - `tool_call_id: string` + + Tool call that this message is responding to. + + - `ChatCompletionFunctionMessageParam object { content, name, role }` + + - `content: string` + + The contents of the function message. + + - `name: string` + + The name of the function to call. + + - `role: "function"` + + The role of the messages author, in this case `function`. + + - `"function"` + +- `model: string or "gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. + + - `string` + + - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. + + - `"gpt-5.4"` + + - `"gpt-5.4-mini"` + + - `"gpt-5.4-nano"` + + - `"gpt-5.4-mini-2026-03-17"` + + - `"gpt-5.4-nano-2026-03-17"` + + - `"gpt-5.3-chat-latest"` + + - `"gpt-5.2"` + + - `"gpt-5.2-2025-12-11"` + + - `"gpt-5.2-chat-latest"` + + - `"gpt-5.2-pro"` + + - `"gpt-5.2-pro-2025-12-11"` + + - `"gpt-5.1"` + + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-5-chat-latest"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` + + - `"o4-mini"` + + - `"o4-mini-2025-04-16"` + + - `"o3"` + + - `"o3-2025-04-16"` + + - `"o3-mini"` + + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"o1-preview"` + + - `"o1-preview-2024-09-12"` + + - `"o1-mini"` + + - `"o1-mini-2024-09-12"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-audio-preview"` + + - `"gpt-4o-audio-preview-2024-10-01"` + + - `"gpt-4o-audio-preview-2024-12-17"` + + - `"gpt-4o-audio-preview-2025-06-03"` + + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` + + - `"gpt-4o-search-preview-2025-03-11"` + + - `"gpt-4o-mini-search-preview-2025-03-11"` + + - `"chatgpt-4o-latest"` + + - `"codex-mini-latest"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0301"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + +- `audio: optional ChatCompletionAudioParam` + + Parameters for audio output. Required when audio output is requested with + `modalities: ["audio"]`. [Learn more](/docs/guides/audio). + + - `format: "wav" or "aac" or "mp3" or 3 more` + + Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, + `opus`, or `pcm16`. + + - `"wav"` + + - `"aac"` + + - `"mp3"` + + - `"flac"` + + - `"opus"` + + - `"pcm16"` + + - `voice: string or "alloy" or "ash" or "ballad" or 7 more or object { id }` + + The voice the model uses to respond. Supported built-in voices are + `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, + `sage`, `shimmer`, `marin`, and `cedar`. You may also provide a + custom voice object with an `id`, for example `{ "id": "voice_1234" }`. + + - `string` + + - `"alloy" or "ash" or "ballad" or 7 more` + + - `"alloy"` + + - `"ash"` + + - `"ballad"` + + - `"coral"` + + - `"echo"` + + - `"sage"` + + - `"shimmer"` + + - `"verse"` + + - `"marin"` + + - `"cedar"` + + - `ID object { id }` + + Custom voice reference. + + - `id: string` + + The custom voice ID, e.g. `voice_1234`. + +- `frequency_penalty: optional number` + + Number between -2.0 and 2.0. Positive values penalize new tokens based on + their existing frequency in the text so far, decreasing the model's + likelihood to repeat the same line verbatim. + +- `function_call: optional "none" or "auto" or ChatCompletionFunctionCallOption` + + Deprecated in favor of `tool_choice`. + + Controls which (if any) function is called by the model. + + `none` means the model will not call a function and instead generates a + message. + + `auto` means the model can pick between generating a message or calling a + function. + + Specifying a particular function via `{"name": "my_function"}` forces the + model to call that function. + + `none` is the default when no functions are present. `auto` is the default + if functions are present. + + - `"none" or "auto"` + + `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. + + - `"none"` + + - `"auto"` + + - `ChatCompletionFunctionCallOption object { name }` + + Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. + + - `name: string` + + The name of the function to call. + +- `functions: optional array of object { name, description, parameters }` + + Deprecated in favor of `tools`. + + A list of functions the model may generate JSON inputs for. + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional FunctionParameters` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + +- `logit_bias: optional map[number]` + + Modify the likelihood of specified tokens appearing in the completion. + + Accepts a JSON object that maps tokens (specified by their token ID in the + tokenizer) to an associated bias value from -100 to 100. Mathematically, + the bias is added to the logits generated by the model prior to sampling. + The exact effect will vary per model, but values between -1 and 1 should + decrease or increase likelihood of selection; values like -100 or 100 + should result in a ban or exclusive selection of the relevant token. + +- `logprobs: optional boolean` + + Whether to return log probabilities of the output tokens or not. If true, + returns the log probabilities of each output token returned in the + `content` of `message`. + +- `max_completion_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + +- `max_tokens: optional number` + + The maximum number of [tokens](/tokenizer) that can be generated in the + chat completion. This value can be used to control + [costs](https://openai.com/api/pricing/) for text generated via API. + + This value is now deprecated in favor of `max_completion_tokens`, and is + not compatible with [o-series models](/docs/guides/reasoning). + +- `metadata: optional Metadata` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +- `modalities: optional array of "text" or "audio"` + + Output types that you would like the model to generate. + Most models are capable of generating text, which is the default: + + `["text"]` + + The `gpt-4o-audio-preview` model can also be used to + [generate audio](/docs/guides/audio). To request that this model generate + both text and audio responses, you can use: + + `["text", "audio"]` + + - `"text"` + + - `"audio"` + +- `n: optional number` + + How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs. + +- `parallel_tool_calls: optional boolean` + + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + +- `prediction: optional ChatCompletionPredictionContent` + + Static predicted output content, such as the content of a text file that is + being regenerated. + + - `content: string or array of ChatCompletionContentPartText` + + The content that should be matched when generating a model response. + If generated tokens would match this content, the entire model response + can be returned much more quickly. + + - `TextContent = string` + + The content used for a Predicted Output. This is often the + text of a file you are regenerating with minor changes. + + - `ArrayOfContentParts = array of ChatCompletionContentPartText` + + An array of content parts with a defined type. Supported options differ based on the [model](/docs/models) being used to generate the response. Can contain text inputs. + + - `text: string` + + The text content. + + - `type: "text"` + + The type of the content part. + + - `type: "content"` + + The type of the predicted content you want to provide. This type is + currently always `content`. + + - `"content"` + +- `presence_penalty: optional number` + + Number between -2.0 and 2.0. Positive values penalize new tokens based on + whether they appear in the text so far, increasing the model's likelihood + to talk about new topics. + +- `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + +- `prompt_cache_retention: optional "in-memory" or "24h"` + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + + - `"in-memory"` + + - `"24h"` + +- `reasoning_effort: optional ReasoningEffort` + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + + - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. + - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. + - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. + - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + +- `response_format: optional ResponseFormatText or ResponseFormatJSONSchema or ResponseFormatJSONObject` + + An object specifying the format that the model must output. + + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables + Structured Outputs which ensures the model will match your supplied JSON + schema. Learn more in the [Structured Outputs + guide](/docs/guides/structured-outputs). + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `ResponseFormatText object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `ResponseFormatJSONSchema object { json_schema, type }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + + - `json_schema: object { name, description, schema, strict }` + + Structured Outputs configuration options, including a JSON Schema. + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `schema: optional map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `ResponseFormatJSONObject object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `type: "json_object"` + + The type of response format being defined. Always `json_object`. + + - `"json_object"` + +- `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +- `seed: optional number` + + This feature is in Beta. + If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. + Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. + +- `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + +- `stop: optional string or array of string` + + Not supported with latest reasoning models `o3` and `o4-mini`. + + Up to 4 sequences where the API will stop generating further tokens. The + returned text will not contain the stop sequence. + + - `string` + + - `array of string` + +- `store: optional boolean` + + Whether or not to store the output of this chat completion request for + use in our [model distillation](/docs/guides/distillation) or + [evals](/docs/guides/evals) products. + + Supports text and image inputs. Note: image inputs over 8MB will be dropped. + +- `stream: optional boolean` + + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/chat/streaming) + for more information, along with the [streaming responses](/docs/guides/streaming-responses) + guide for more information on how to handle the streaming events. + +- `stream_options: optional ChatCompletionStreamOptions` + + Options for streaming response. Only set this when you set `stream: true`. + + - `include_obfuscation: optional boolean` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + + - `include_usage: optional boolean` + + If set, an additional chunk will be streamed before the `data: [DONE]` + message. The `usage` field on this chunk shows the token usage statistics + for the entire request, and the `choices` field will always be an empty + array. + + All other chunks will also include a `usage` field, but with a null + value. **NOTE:** If the stream is interrupted, you may not receive the + final usage chunk which contains the total token usage for the request. + +- `temperature: optional number` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + +- `tool_choice: optional ChatCompletionToolChoiceOption` + + Controls which (if any) tool is called by the model. + `none` means the model will not call any tool and instead generates a message. + `auto` means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools. + Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + + `none` is the default when no tools are present. `auto` is the default if tools are present. + + - `ToolChoiceMode = "none" or "auto" or "required"` + + `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `ChatCompletionAllowedToolChoice object { allowed_tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `allowed_tools: ChatCompletionAllowedTools` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Chat Completions API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "function": { "name": "get_weather" } }, + { "type": "function", "function": { "name": "get_time" } } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `ChatCompletionNamedToolChoice object { function, type }` + + Specifies a tool the model should use. Use to force the model to call a specific function. + + - `function: object { name }` + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `"function"` + + - `ChatCompletionNamedToolChoiceCustom object { custom, type }` + + Specifies a tool the model should use. Use to force the model to call a specific custom tool. + + - `custom: object { name }` + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + +- `tools: optional array of ChatCompletionTool` + + A list of tools the model may call. You can provide either + [custom tools](/docs/guides/function-calling#custom-tools) or + [function tools](/docs/guides/function-calling). + + - `ChatCompletionFunctionTool object { function, type }` + + A function tool that can be used to generate a response. + + - `function: FunctionDefinition` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional FunctionParameters` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + + - `type: "function"` + + The type of the tool. Currently, only `function` is supported. + + - `"function"` + + - `ChatCompletionCustomTool object { custom, type }` + + A custom tool that processes input using a specified format. + + - `custom: object { name, description, format }` + + Properties of the custom tool. + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { grammar, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `TextFormat object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `GrammarFormat object { grammar, type }` + + A grammar defined by the user. + + - `grammar: object { definition, syntax }` + + Your chosen grammar. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + +- `top_logprobs: optional number` + + An integer between 0 and 20 specifying the number of most likely tokens to + return at each token position, each with an associated log probability. + `logprobs` must be set to `true` if this parameter is used. + +- `top_p: optional number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + +- `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +- `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + +- `web_search_options: optional object { search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. + Learn more about the [web search tool](/docs/guides/tools-web-search?api-mode=chat). + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the + search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { approximate, type }` + + Approximate location parameters for the search. + + - `approximate: object { city, country, region, timezone }` + + Approximate location parameters for the search. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter + [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, + e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) + of the user, e.g. `America/Los_Angeles`. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + +### Returns + +- `ChatCompletion object { id, choices, created, 5 more }` + + Represents a chat completion response returned by model, based on the provided input. + + - `id: string` + + A unique identifier for the chat completion. + + - `choices: array of object { finish_reason, index, logprobs, message }` + + A list of chat completion choices. Can be more than one if `n` is greater than 1. + + - `finish_reason: "stop" or "length" or "tool_calls" or 2 more` + + The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, + `length` if the maximum number of tokens specified in the request was reached, + `content_filter` if content was omitted due to a flag from our content filters, + `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. + + - `"stop"` + + - `"length"` + + - `"tool_calls"` + + - `"content_filter"` + + - `"function_call"` + + - `index: number` + + The index of the choice in the list of choices. + + - `logprobs: object { content, refusal }` + + Log probability information for the choice. + + - `content: array of ChatCompletionTokenLogprob` + + A list of message content tokens with log probability information. + + - `token: string` + + The token. + + - `bytes: array of number` + + A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. + + - `logprob: number` + + The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. + + - `top_logprobs: array of object { token, bytes, logprob }` + + List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned. + + - `token: string` + + The token. + + - `bytes: array of number` + + A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. + + - `logprob: number` + + The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. + + - `refusal: array of ChatCompletionTokenLogprob` + + A list of message refusal tokens with log probability information. + + - `token: string` + + The token. + + - `bytes: array of number` + + A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. + + - `logprob: number` + + The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. + + - `top_logprobs: array of object { token, bytes, logprob }` + + List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned. + + - `message: ChatCompletionMessage` + + A chat completion message generated by the model. + + - `content: string` + + The contents of the message. + + - `refusal: string` + + The refusal message generated by the model. + + - `role: "assistant"` + + The role of the author of this message. + + - `"assistant"` + + - `annotations: optional array of object { type, url_citation }` + + Annotations for the message, when applicable, as when using the + [web search tool](/docs/guides/tools-web-search?api-mode=chat). + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url_citation: object { end_index, start_index, title, url }` + + A URL citation when using web search. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `url: string` + + The URL of the web resource. + + - `audio: optional ChatCompletionAudio` + + If the audio output modality is requested, this object contains data + about the audio response from the model. [Learn more](/docs/guides/audio). + + - `id: string` + + Unique identifier for this audio response. + + - `data: string` + + Base64 encoded audio bytes generated by the model, in the format + specified in the request. + + - `expires_at: number` + + The Unix timestamp (in seconds) for when this audio response will + no longer be accessible on the server for use in multi-turn + conversations. + + - `transcript: string` + + Transcript of the audio generated by the model. + + - `function_call: optional object { arguments, name }` + + Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. + + - `arguments: string` + + The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + + - `name: string` + + The name of the function to call. + + - `tool_calls: optional array of ChatCompletionMessageToolCall` + + The tool calls generated by the model, such as function calls. + + - `ChatCompletionMessageFunctionToolCall object { id, function, type }` + + A call to a function tool created by the model. + + - `id: string` + + The ID of the tool call. + + - `function: object { arguments, name }` + + The function that the model called. + + - `arguments: string` + + The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + The type of the tool. Currently, only `function` is supported. + + - `"function"` + + - `ChatCompletionMessageCustomToolCall object { id, custom, type }` + + A call to a custom tool created by the model. + + - `id: string` + + The ID of the tool call. + + - `custom: object { input, name }` + + The custom tool that the model called. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + The type of the tool. Always `custom`. + + - `"custom"` + + - `created: number` + + The Unix timestamp (in seconds) of when the chat completion was created. + + - `model: string` + + The model used for the chat completion. + + - `object: "chat.completion"` + + The object type, which is always `chat.completion`. + + - `"chat.completion"` + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `system_fingerprint: optional string` + + This fingerprint represents the backend configuration that the model runs with. + + Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. + + - `usage: optional CompletionUsage` + + Usage statistics for the completion request. + + - `completion_tokens: number` + + Number of tokens in the generated completion. + + - `prompt_tokens: number` + + Number of tokens in the prompt. + + - `total_tokens: number` + + Total number of tokens used in the request (prompt + completion). + + - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }` + + Breakdown of tokens used in a completion. + + - `accepted_prediction_tokens: optional number` + + When using Predicted Outputs, the number of tokens in the + prediction that appeared in the completion. + + - `audio_tokens: optional number` + + Audio input tokens generated by the model. + + - `reasoning_tokens: optional number` + + Tokens generated by the model for reasoning. + + - `rejected_prediction_tokens: optional number` + + When using Predicted Outputs, the number of tokens in the + prediction that did not appear in the completion. However, like + reasoning tokens, these tokens are still counted in the total + completion tokens for purposes of billing, output, and context window + limits. + + - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }` + + Breakdown of tokens used in the prompt. + + - `audio_tokens: optional number` + + Audio input tokens present in the prompt. + + - `cached_tokens: optional number` + + Cached tokens present in the prompt. + +### Example + +```http +curl https://api.openai.com/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "messages": [ + { + "content": "string", + "role": "developer" + } + ], + "model": "gpt-5.4", + "n": 1, + "prompt_cache_key": "prompt-cache-key-1234", + "safety_identifier": "safety-identifier-1234", + "temperature": 1, + "top_p": 1, + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "id": "id", + "choices": [ + { + "finish_reason": "stop", + "index": 0, + "logprobs": { + "content": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "refusal": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + }, + "message": { + "content": "content", + "refusal": "refusal", + "role": "assistant", + "annotations": [ + { + "type": "url_citation", + "url_citation": { + "end_index": 0, + "start_index": 0, + "title": "title", + "url": "url" + } + } + ], + "audio": { + "id": "id", + "data": "data", + "expires_at": 0, + "transcript": "transcript" + }, + "function_call": { + "arguments": "arguments", + "name": "name" + }, + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + } + } + ], + "created": 0, + "model": "model", + "object": "chat.completion", + "service_tier": "auto", + "system_fingerprint": "system_fingerprint", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0, + "completion_tokens_details": { + "accepted_prediction_tokens": 0, + "audio_tokens": 0, + "reasoning_tokens": 0, + "rejected_prediction_tokens": 0 + }, + "prompt_tokens_details": { + "audio_tokens": 0, + "cached_tokens": 0 + } + } +} +``` + +### Example + +```http +curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "developer", + "content": "You are a helpful assistant." + }, + { + "role": "user", + "content": "Hello!" + } + ] + }' +``` + +#### Response + +```json +{ + "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT", + "object": "chat.completion", + "created": 1741569952, + "model": "gpt-5.4", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I assist you today?", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 19, + "completion_tokens": 10, + "total_tokens": 29, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, + "completion_tokens_details": { + "reasoning_tokens": 0, + "audio_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "service_tier": "default" +} +``` + +### Image input + +```http +curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "What is in this image?" + }, + { + "type": "image_url", + "image_url": { + "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + } + ] + } + ], + "max_tokens": 300 + }' +``` + +#### Response + +```json +{ + "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", + "object": "chat.completion", + "created": 1741570283, + "model": "gpt-5.4", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 1117, + "completion_tokens": 46, + "total_tokens": 1163, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, + "completion_tokens_details": { + "reasoning_tokens": 0, + "audio_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "service_tier": "default" +} +``` + +### Streaming + +```http +curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "developer", + "content": "You are a helpful assistant." + }, + { + "role": "user", + "content": "Hello!" + } + ], + "stream": true + }' +``` + +#### Response + +```json +{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} + +{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} + +.... + +{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} +``` + +### Functions + +```http +curl https://api.openai.com/v1/chat/completions \ +-H "Content-Type: application/json" \ +-H "Authorization: Bearer $OPENAI_API_KEY" \ +-d '{ + "model": "gpt-5.4", + "messages": [ + { + "role": "user", + "content": "What is the weather like in Boston today?" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "tool_choice": "auto" +}' +``` + +#### Response + +```json +{ + "id": "chatcmpl-abc123", + "object": "chat.completion", + "created": 1699896916, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": null, + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\n\"location\": \"Boston, MA\"\n}" + } + } + ] + }, + "logprobs": null, + "finish_reason": "tool_calls" + } + ], + "usage": { + "prompt_tokens": 82, + "completion_tokens": 17, + "total_tokens": 99, + "completion_tokens_details": { + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + } +} +``` + +### Logprobs + +```http +curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "user", + "content": "Hello!" + } + ], + "logprobs": true, + "top_logprobs": 2 + }' +``` + +#### Response + +```json +{ + "id": "chatcmpl-123", + "object": "chat.completion", + "created": 1702685778, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I assist you today?" + }, + "logprobs": { + "content": [ + { + "token": "Hello", + "logprob": -0.31725305, + "bytes": [72, 101, 108, 108, 111], + "top_logprobs": [ + { + "token": "Hello", + "logprob": -0.31725305, + "bytes": [72, 101, 108, 108, 111] + }, + { + "token": "Hi", + "logprob": -1.3190403, + "bytes": [72, 105] + } + ] + }, + { + "token": "!", + "logprob": -0.02380986, + "bytes": [ + 33 + ], + "top_logprobs": [ + { + "token": "!", + "logprob": -0.02380986, + "bytes": [33] + }, + { + "token": " there", + "logprob": -3.787621, + "bytes": [32, 116, 104, 101, 114, 101] + } + ] + }, + { + "token": " How", + "logprob": -0.000054669687, + "bytes": [32, 72, 111, 119], + "top_logprobs": [ + { + "token": " How", + "logprob": -0.000054669687, + "bytes": [32, 72, 111, 119] + }, + { + "token": "<|end|>", + "logprob": -10.953937, + "bytes": null + } + ] + }, + { + "token": " can", + "logprob": -0.015801601, + "bytes": [32, 99, 97, 110], + "top_logprobs": [ + { + "token": " can", + "logprob": -0.015801601, + "bytes": [32, 99, 97, 110] + }, + { + "token": " may", + "logprob": -4.161023, + "bytes": [32, 109, 97, 121] + } + ] + }, + { + "token": " I", + "logprob": -3.7697225e-6, + "bytes": [ + 32, + 73 + ], + "top_logprobs": [ + { + "token": " I", + "logprob": -3.7697225e-6, + "bytes": [32, 73] + }, + { + "token": " assist", + "logprob": -13.596657, + "bytes": [32, 97, 115, 115, 105, 115, 116] + } + ] + }, + { + "token": " assist", + "logprob": -0.04571125, + "bytes": [32, 97, 115, 115, 105, 115, 116], + "top_logprobs": [ + { + "token": " assist", + "logprob": -0.04571125, + "bytes": [32, 97, 115, 115, 105, 115, 116] + }, + { + "token": " help", + "logprob": -3.1089056, + "bytes": [32, 104, 101, 108, 112] + } + ] + }, + { + "token": " you", + "logprob": -5.4385737e-6, + "bytes": [32, 121, 111, 117], + "top_logprobs": [ + { + "token": " you", + "logprob": -5.4385737e-6, + "bytes": [32, 121, 111, 117] + }, + { + "token": " today", + "logprob": -12.807695, + "bytes": [32, 116, 111, 100, 97, 121] + } + ] + }, + { + "token": " today", + "logprob": -0.0040071653, + "bytes": [32, 116, 111, 100, 97, 121], + "top_logprobs": [ + { + "token": " today", + "logprob": -0.0040071653, + "bytes": [32, 116, 111, 100, 97, 121] + }, + { + "token": "?", + "logprob": -5.5247097, + "bytes": [63] + } + ] + }, + { + "token": "?", + "logprob": -0.0008108172, + "bytes": [63], + "top_logprobs": [ + { + "token": "?", + "logprob": -0.0008108172, + "bytes": [63] + }, + { + "token": "?\n", + "logprob": -7.184561, + "bytes": [63, 10] + } + ] + } + ] + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 9, + "completion_tokens": 9, + "total_tokens": 18, + "completion_tokens_details": { + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "system_fingerprint": null +} +``` diff --git a/docs/api_reference/openai/chat_response.md b/docs/api_reference/openai/chat_response.md new file mode 100644 index 0000000..34a973d --- /dev/null +++ b/docs/api_reference/openai/chat_response.md @@ -0,0 +1,11522 @@ +## Create a model response + +**post** `/responses` + +Creates a model response. Provide [text](/docs/guides/text) or +[image](/docs/guides/images) inputs to generate [text](/docs/guides/text) +or [JSON](/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](/docs/guides/function-calling) or use built-in +[tools](/docs/guides/tools) like [web search](/docs/guides/tools-web-search) +or [file search](/docs/guides/tools-file-search) to use your own data +as input for the model's response. + +### Body Parameters + +- `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](/docs/guides/background). + +- `context_management: optional array of object { type, compact_threshold }` + + Context management configuration for this request. + + - `type: string` + + The context management entry type. Currently only 'compaction' is supported. + + - `compact_threshold: optional number` + + Token threshold at which compaction should be triggered for this entry. + +- `conversation: optional string or ResponseConversationParam` + + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. + + - `ConversationID = string` + + The unique ID of the conversation. + + - `ResponseConversationParam object { id }` + + The conversation that this response belongs to. + + - `id: string` + + The unique ID of the conversation. + +- `include: optional array of ResponseIncludable` + + Specify additional output data to include in the model response. Currently supported values are: + + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + + - `"file_search_call.results"` + + - `"web_search_call.results"` + + - `"web_search_call.action.sources"` + + - `"message.input_image.image_url"` + + - `"computer_call_output.output.image_url"` + + - `"code_interpreter_call.outputs"` + + - `"reasoning.encrypted_content"` + + - `"message.output_text.logprobs"` + +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + Text, image, or file inputs to the model, used to generate a response. + + Learn more: + + - [Text inputs and outputs](/docs/guides/text) + - [Image inputs](/docs/guides/images) + - [File inputs](/docs/guides/pdf-files) + - [Conversation state](/docs/guides/conversation-state) + - [Function calling](/docs/guides/function-calling) + + - `TextInput = string` + + A text input to the model, equivalent to a text input with the + `user` role. + + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + A list of one or many input items to the model, containing + different content types. + + - `EasyInputMessage object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or ResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `TextInput = string` + + A text input to the model. + + - `ResponseInputMessageContentList = array of ResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `Message object { content, role, status, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: ResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `ResponseOutputMessage object { id, content, role, 3 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of ResponseOutputText or ResponseOutputRefusal` + + The content of the output message. + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `"message"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `FileSearchCall object { id, queries, status, 2 more }` + + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `string` + + - `number` + + - `boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional ComputerAction` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional ComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + + - `ComputerCallOutput object { call_id, output, type, 3 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `WebSearchCall object { id, action, status, type }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { query, type, queries, sources }` + + Action type "search" - Performs a web search query. + + - `query: string` + + [DEPRECATED] The search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `FunctionCall object { arguments, call_id, name, 4 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { call_id, output, type, 2 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + Text, image, or file output of the function tool call. + + - `string` + + A JSON string of the output of the function tool call. + + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + An array of content outputs (text, image, file) for the function tool call. + + - `ResponseInputTextContent object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImageContent object { type, detail, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { arguments, type, id, 3 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: optional string` + + The unique ID of this tool search call. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchOutput object { tools, type, id, 3 more }` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The loaded tool definitions returned by the tool search output. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `string` + + - `number` + + - `boolean` + + - `array of string or number` + + - `string` + + - `number` + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of ComparisonFilter or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of SkillReference or InlineSkill` + + An optional list of skills referenced by id or inline data. + + - `SkillReference object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `InlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: InlineSkillSource` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: "inline"` + + Defines an inline skill for this request. + + - `"inline"` + + - `LocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of LocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `ContainerReference object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `Grammar object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Reasoning object { id, summary, type, 3 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 3 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `environment: optional LocalEnvironment or ContainerReference` + + The environment to execute the shell commands in. + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 3 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of ResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 2 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, id }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `ItemReference object { id, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + +- `instructions: optional string` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + +- `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + +- `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + +- `metadata: optional Metadata` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +- `model: optional ResponsesModel` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. + + - `string` + + - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + + - `"gpt-5.4"` + + - `"gpt-5.4-mini"` + + - `"gpt-5.4-nano"` + + - `"gpt-5.4-mini-2026-03-17"` + + - `"gpt-5.4-nano-2026-03-17"` + + - `"gpt-5.3-chat-latest"` + + - `"gpt-5.2"` + + - `"gpt-5.2-2025-12-11"` + + - `"gpt-5.2-chat-latest"` + + - `"gpt-5.2-pro"` + + - `"gpt-5.2-pro-2025-12-11"` + + - `"gpt-5.1"` + + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-5-chat-latest"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` + + - `"o4-mini"` + + - `"o4-mini-2025-04-16"` + + - `"o3"` + + - `"o3-2025-04-16"` + + - `"o3-mini"` + + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"o1-preview"` + + - `"o1-preview-2024-09-12"` + + - `"o1-mini"` + + - `"o1-mini-2024-09-12"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-audio-preview"` + + - `"gpt-4o-audio-preview-2024-10-01"` + + - `"gpt-4o-audio-preview-2024-12-17"` + + - `"gpt-4o-audio-preview-2025-06-03"` + + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` + + - `"gpt-4o-search-preview-2025-03-11"` + + - `"gpt-4o-mini-search-preview-2025-03-11"` + + - `"chatgpt-4o-latest"` + + - `"codex-mini-latest"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0301"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + + - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + +- `parallel_tool_calls: optional boolean` + + Whether to allow the model to run tool calls in parallel. + +- `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + +- `prompt: optional ResponsePrompt` + + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `string` + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `version: optional string` + + Optional version of the prompt template. + +- `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + +- `prompt_cache_retention: optional "in-memory" or "24h"` + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + + - `"in-memory"` + + - `"24h"` + +- `reasoning: optional Reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `effort: optional ReasoningEffort` + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + + - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. + - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. + - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. + - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + +- `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +- `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + +- `store: optional boolean` + + Whether to store the generated model response for later retrieval via + API. + +- `stream: optional boolean` + + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/responses-streaming) + for more information. + +- `stream_options: optional object { include_obfuscation }` + + Options for streaming responses. Only set this when you set `stream: true`. + + - `include_obfuscation: optional boolean` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + +- `temperature: optional number` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + +- `text: optional ResponseTextConfig` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) + + - `format: optional ResponseFormatTextConfig` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `ResponseFormatText object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). + + - `ResponseFormatJSONObject object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `type: "json_object"` + + The type of response format being defined. Always `json_object`. + + - `"json_object"` + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + +- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 5 more` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `ToolChoiceOptions = "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `ToolChoiceAllowed object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `ToolChoiceTypes object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `ToolChoiceFunction object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `"function"` + + - `ToolChoiceMcp object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: optional string` + + The name of the tool to call on the server. + + - `ToolChoiceCustom object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `ToolChoiceApplyPatch object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `ToolChoiceShell object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `"shell"` + +- `tools: optional array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + +- `top_logprobs: optional number` + + An integer between 0 and 20 specifying the number of most likely tokens to + return at each token position, each with an associated log probability. + +- `top_p: optional number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + +- `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + +- `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +### Returns + +- `Response object { id, created_at, error, 30 more }` + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: ResponseError` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 15 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `string` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + A list of one or many input items to the model, containing + different content types. + + - `EasyInputMessage object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or ResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `TextInput = string` + + A text input to the model. + + - `ResponseInputMessageContentList = array of ResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `Message object { content, role, status, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: ResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `ResponseOutputMessage object { id, content, role, 3 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of ResponseOutputText or ResponseOutputRefusal` + + The content of the output message. + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `"message"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `FileSearchCall object { id, queries, status, 2 more }` + + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `string` + + - `number` + + - `boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional ComputerAction` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional ComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + + - `ComputerCallOutput object { call_id, output, type, 3 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `WebSearchCall object { id, action, status, type }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { query, type, queries, sources }` + + Action type "search" - Performs a web search query. + + - `query: string` + + [DEPRECATED] The search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `FunctionCall object { arguments, call_id, name, 4 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { call_id, output, type, 2 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + Text, image, or file output of the function tool call. + + - `string` + + A JSON string of the output of the function tool call. + + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + An array of content outputs (text, image, file) for the function tool call. + + - `ResponseInputTextContent object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImageContent object { type, detail, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { arguments, type, id, 3 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: optional string` + + The unique ID of this tool search call. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchOutput object { tools, type, id, 3 more }` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The loaded tool definitions returned by the tool search output. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `string` + + - `number` + + - `boolean` + + - `array of string or number` + + - `string` + + - `number` + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of ComparisonFilter or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of SkillReference or InlineSkill` + + An optional list of skills referenced by id or inline data. + + - `SkillReference object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `InlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: InlineSkillSource` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: "inline"` + + Defines an inline skill for this request. + + - `"inline"` + + - `LocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of LocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `ContainerReference object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `Grammar object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Reasoning object { id, summary, type, 3 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 3 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `environment: optional LocalEnvironment or ContainerReference` + + The environment to execute the shell commands in. + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 3 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of ResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 2 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, id }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `ItemReference object { id, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `metadata: Metadata` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + + - `model: ResponsesModel` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. + + - `string` + + - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + + - `"gpt-5.4"` + + - `"gpt-5.4-mini"` + + - `"gpt-5.4-nano"` + + - `"gpt-5.4-mini-2026-03-17"` + + - `"gpt-5.4-nano-2026-03-17"` + + - `"gpt-5.3-chat-latest"` + + - `"gpt-5.2"` + + - `"gpt-5.2-2025-12-11"` + + - `"gpt-5.2-chat-latest"` + + - `"gpt-5.2-pro"` + + - `"gpt-5.2-pro-2025-12-11"` + + - `"gpt-5.1"` + + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-5-chat-latest"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` + + - `"o4-mini"` + + - `"o4-mini-2025-04-16"` + + - `"o3"` + + - `"o3-2025-04-16"` + + - `"o3-mini"` + + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"o1-preview"` + + - `"o1-preview-2024-09-12"` + + - `"o1-mini"` + + - `"o1-mini-2024-09-12"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-audio-preview"` + + - `"gpt-4o-audio-preview-2024-10-01"` + + - `"gpt-4o-audio-preview-2024-12-17"` + + - `"gpt-4o-audio-preview-2025-06-03"` + + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` + + - `"gpt-4o-search-preview-2025-03-11"` + + - `"gpt-4o-mini-search-preview-2025-03-11"` + + - `"chatgpt-4o-latest"` + + - `"codex-mini-latest"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0301"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + + - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `object: "response"` + + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: array of ResponseOutputItem` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `ResponseOutputMessage object { id, content, role, 3 more }` + + An output message from the model. + + - `FileSearchCall object { id, queries, status, 2 more }` + + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `string` + + - `number` + + - `boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `FunctionCall object { arguments, call_id, name, 4 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { id, call_id, output, 3 more }` + + - `id: string` + + The unique ID of the function call tool output. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the function call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the function call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `WebSearchCall object { id, action, status, type }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { query, type, queries, sources }` + + Action type "search" - Performs a web search query. + + - `query: string` + + [DEPRECATED] The search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional ComputerAction` + + A click action. + + - `actions: optional ComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `ComputerCallOutput object { id, call_id, output, 4 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `Reasoning object { id, summary, type, 3 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { id, arguments, call_id, 4 more }` + + - `id: string` + + The unique ID of the tool search call item. + + - `arguments: unknown` + + Arguments used for the tool search call. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `"tool_search_call"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 4 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The loaded tool definitions returned by tool search. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `Compaction object { id, encrypted_content, type, created_by }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { id, action, call_id, 4 more }` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + - `max_output_length: number` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: number` + + Optional timeout in milliseconds for the commands. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `environment: ResponseLocalEnvironment or ResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `ResponseLocalEnvironment object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `"local"` + + - `ResponseContainerReference object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `"container_reference"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + + The output of a shell tool call that was emitted. + + - `id: string` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: number` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents + + - `outcome: object { type } or object { exit_code, type }` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"shell_call_output"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ApplyPatchCall object { id, call_id, operation, 3 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `CreateFile object { diff, path, type }` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `created_by: optional string` + + The ID of the entity that created this tool call output. + + - `output: optional string` + + Optional textual output returned by the apply patch tool. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + + A response to an MCP approval request. + + - `id: string` + + The unique ID of the approval response + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `reason: optional string` + + Optional reason for the decision. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `CustomToolCallOutput object { id, call_id, output, 3 more }` + + - `id: string` + + The unique ID of the custom tool call output item. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: boolean` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: number` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 5 more` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `ToolChoiceOptions = "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `ToolChoiceAllowed object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `ToolChoiceTypes object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `ToolChoiceFunction object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `"function"` + + - `ToolChoiceMcp object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: optional string` + + The name of the tool to call on the server. + + - `ToolChoiceCustom object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `ToolChoiceApplyPatch object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `ToolChoiceShell object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `"shell"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](/docs/guides/background). + + - `completed_at: optional number` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: optional object { id }` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: string` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `output_text: optional string` + + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. + + - `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: optional ResponsePrompt` + + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `string` + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `version: optional string` + + Optional version of the prompt template. + + - `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + + - `prompt_cache_retention: optional "in-memory" or "24h"` + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + + - `"in-memory"` + + - `"24h"` + + - `reasoning: optional Reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `effort: optional ReasoningEffort` + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + + - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. + - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. + - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. + - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: optional ResponseStatus` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: optional ResponseTextConfig` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) + + - `format: optional ResponseFormatTextConfig` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `ResponseFormatText object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). + + - `ResponseFormatJSONObject object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `type: "json_object"` + + The type of response format being defined. Always `json_object`. + + - `"json_object"` + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: optional number` + + An integer between 0 and 20 specifying the number of most likely tokens to + return at each token position, each with an associated log probability. + + - `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: optional ResponseUsage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: number` + + The number of input tokens. + + - `input_tokens_details: object { cached_tokens }` + + A detailed breakdown of the input tokens. + + - `cached_tokens: number` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). + + - `output_tokens: number` + + The number of output tokens. + + - `output_tokens_details: object { reasoning_tokens }` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: number` + + The number of reasoning tokens. + + - `total_tokens: number` + + The total number of tokens used. + + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +### Example + +```http +curl https://api.openai.com/v1/responses \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.1", + "prompt_cache_key": "prompt-cache-key-1234", + "safety_identifier": "safety-identifier-1234", + "temperature": 1, + "top_p": 1, + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "defer_loading": true, + "description": "description" + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_retention": "in-memory", + "reasoning": { + "effort": "none", + "generate_summary": "auto", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +### Text input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "Tell me a three sentence bedtime story about a unicorn." + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "object": "response", + "created_at": 1741476542, + "status": "completed", + "completed_at": 1741476543, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 36, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} +} +``` + +### Image input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this image?"}, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "completed_at": 1741476778, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} +} +``` + +### File input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this file?"}, + { + "type": "input_file", + "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", + "object": "response", + "created_at": 1752100704, + "status": "completed", + "completed_at": 1752100705, + "background": false, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "max_tool_calls": null, + "model": "gpt-5.4", + "output": [ + { + "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." + } + ], + "role": "assistant" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "service_tier": "default", + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_logprobs": 0, + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 8438, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 398, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 8836 + }, + "user": null, + "metadata": {} +} +``` + +### Web search + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ "type": "web_search_preview" }], + "input": "What was a positive news story from today?" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", + "object": "response", + "created_at": 1741484430, + "status": "completed", + "completed_at": 1741484431, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "web_search_call", + "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", + "status": "completed" + }, + { + "type": "message", + "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "As of today, March 9, 2025, one notable positive news story...", + "annotations": [ + { + "type": "url_citation", + "start_index": 442, + "end_index": 557, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 962, + "end_index": 1077, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 1336, + "end_index": 1451, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "web_search_preview", + "domains": [], + "search_context_size": "medium", + "user_location": { + "type": "approximate", + "city": null, + "country": "US", + "region": null, + "timezone": null + } + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} +} +``` + +### File search + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + "input": "What are the attributes of an ancient brown dragon?" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "completed_at": 1741485254, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} +} +``` + +### Streaming + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "instructions": "You are a helpful assistant.", + "input": "Hello!", + "stream": true + }' +``` + +#### Response + +```json +event: response.created +data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + +event: response.in_progress +data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + +event: response.output_item.added +data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} + +event: response.content_part.added +data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + +... + +event: response.output_text.done +data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} + +event: response.content_part.done +data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} + +event: response.output_item.done +data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} + +event: response.completed +data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} +``` + +### Functions + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "What is the weather like in Boston today?", + "tools": [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location", "unit"] + } + } + ], + "tool_choice": "auto" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "completed_at": 1741294022, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} +} +``` + +### Reasoning + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "o3-mini", + "input": "How much wood would a woodchuck chuck?", + "reasoning": { + "effort": "high" + } + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", + "object": "response", + "created_at": 1741477868, + "status": "completed", + "completed_at": 1741477869, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "o1-2024-12-17", + "output": [ + { + "type": "message", + "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The classic tongue twister...", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": "high", + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 81, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} +} +``` diff --git a/docs/api_reference/openai/count_token.md b/docs/api_reference/openai/count_token.md new file mode 100644 index 0000000..01c11b6 --- /dev/null +++ b/docs/api_reference/openai/count_token.md @@ -0,0 +1,3939 @@ +## Get input token counts + +**post** `/responses/input_tokens` + +Returns input token counts of the request. + +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + +### Body Parameters + +- `conversation: optional string or ResponseConversationParam` + + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. + + - `ConversationID = string` + + The unique ID of the conversation. + + - `ResponseConversationParam object { id }` + + The conversation that this response belongs to. + + - `id: string` + + The unique ID of the conversation. + +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + Text, image, or file inputs to the model, used to generate a response + + - `string` + + A text input to the model, equivalent to a text input with the `user` role. + + - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 25 more` + + A list of one or many input items to the model, containing different content types. + + - `EasyInputMessage object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or ResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `TextInput = string` + + A text input to the model. + + - `ResponseInputMessageContentList = array of ResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `Message object { content, role, status, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: ResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `ResponseOutputMessage object { id, content, role, 3 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of ResponseOutputText or ResponseOutputRefusal` + + The content of the output message. + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `"message"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `FileSearchCall object { id, queries, status, 2 more }` + + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `string` + + - `number` + + - `boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional ComputerAction` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional ComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + + - `ComputerCallOutput object { call_id, output, type, 3 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `WebSearchCall object { id, action, status, type }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { query, type, queries, sources }` + + Action type "search" - Performs a web search query. + + - `query: string` + + [DEPRECATED] The search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `FunctionCall object { arguments, call_id, name, 4 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { call_id, output, type, 2 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + Text, image, or file output of the function tool call. + + - `string` + + A JSON string of the output of the function tool call. + + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + An array of content outputs (text, image, file) for the function tool call. + + - `ResponseInputTextContent object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImageContent object { type, detail, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "low" or "high"` + + The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { arguments, type, id, 3 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: optional string` + + The unique ID of this tool search call. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchOutput object { tools, type, id, 3 more }` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The loaded tool definitions returned by the tool search output. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `string` + + - `number` + + - `boolean` + + - `array of string or number` + + - `string` + + - `number` + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of ComparisonFilter or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of SkillReference or InlineSkill` + + An optional list of skills referenced by id or inline data. + + - `SkillReference object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `InlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: InlineSkillSource` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: "inline"` + + Defines an inline skill for this request. + + - `"inline"` + + - `LocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of LocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `ContainerReference object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `Grammar object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Reasoning object { id, summary, type, 3 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 3 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `environment: optional LocalEnvironment or ContainerReference` + + The environment to execute the shell commands in. + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 3 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of ResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 2 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, id }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `ItemReference object { id, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + +- `instructions: optional string` + + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + +- `model: optional string` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. + +- `parallel_tool_calls: optional boolean` + + Whether to allow the model to run tool calls in parallel. + +- `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + +- `reasoning: optional Reasoning` + + **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `effort: optional ReasoningEffort` + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + + - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. + - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. + - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. + - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + +- `text: optional object { format, verbosity }` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) + + - `format: optional ResponseFormatTextConfig` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `ResponseFormatText object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). + + - `ResponseFormatJSONObject object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `type: "json_object"` + + The type of response format being defined. Always `json_object`. + + - `"json_object"` + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + +- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 5 more` + + Controls which tool the model should use, if any. + + - `ToolChoiceOptions = "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `ToolChoiceAllowed object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `ToolChoiceTypes object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `ToolChoiceFunction object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `"function"` + + - `ToolChoiceMcp object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: optional string` + + The name of the tool to call on the server. + + - `ToolChoiceCustom object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `ToolChoiceApplyPatch object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `ToolChoiceShell object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `"shell"` + +- `tools: optional array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated image. One of `1024x1024`, `1024x1536`, + `1536x1024`, or `auto`. Default: `auto`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + +- `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + +### Returns + +- `input_tokens: number` + +- `object: "response.input_tokens"` + + - `"response.input_tokens"` + +### Example + +```http +curl https://api.openai.com/v1/responses/input_tokens \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` + +### Example + +```http +curl -X POST https://api.openai.com/v1/responses/input_tokens \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5", + "input": "Tell me a joke." + }' +``` + +#### Response + +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` diff --git a/docs/api_reference/openai/models.md b/docs/api_reference/openai/models.md new file mode 100644 index 0000000..7e4262d --- /dev/null +++ b/docs/api_reference/openai/models.md @@ -0,0 +1,89 @@ +## List models + +**get** `/models` + +Lists the currently available models, and provides basic information about each one such as the owner and availability. + +### Returns + +- `data: array of Model` + + - `id: string` + + The model identifier, which can be referenced in the API endpoints. + + - `created: number` + + The Unix timestamp (in seconds) when the model was created. + + - `object: "model"` + + The object type, which is always "model". + + - `"model"` + + - `owned_by: string` + + The organization that owns the model. + +- `object: "list"` + + - `"list"` + +### Example + +```http +curl https://api.openai.com/v1/models \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "data": [ + { + "id": "id", + "created": 0, + "object": "model", + "owned_by": "owned_by" + } + ], + "object": "list" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/models \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "object": "list", + "data": [ + { + "id": "model-id-0", + "object": "model", + "created": 1686935002, + "owned_by": "organization-owner" + }, + { + "id": "model-id-1", + "object": "model", + "created": 1686935002, + "owned_by": "organization-owner", + }, + { + "id": "model-id-2", + "object": "model", + "created": 1686935002, + "owned_by": "openai" + }, + ] +} +``` diff --git a/docs/conversion_design.md b/docs/conversion_design.md new file mode 100644 index 0000000..139b95b --- /dev/null +++ b/docs/conversion_design.md @@ -0,0 +1,1707 @@ +# LLM API Protocol Conversion Layer — Architecture Design + +> 语言无关的 HTTP 层 SDK。以 Hub-and-Spoke 架构实现 OpenAI / Anthropic 协议间的双向转换，覆盖完整 HTTP 接口体系，同协议自动透传，为新协议和多模态预留扩展点。 + +--- + +## 目录 + +1. [设计目标与约束](#1-设计目标与约束) +2. [架构总览](#2-架构总览) +3. [接口体系分层](#3-接口体系分层) +4. [Canonical Model（规范模型）](#4-canonical-model规范模型) +5. [Protocol Adapter 接口](#5-protocol-adapter-接口) +6. [Conversion Engine（转换引擎）](#6-conversion-engine转换引擎) +7. [流式转换架构](#7-流式转换架构) +8. [OpenAI 协议适配器](#8-openai-协议适配器) +9. [Anthropic 协议适配器](#9-anthropic-协议适配器) +10. [字段映射参考](#10-字段映射参考) +11. [扩展点设计](#11-扩展点设计) +12. [错误处理](#12-错误处理) +13. [参考实现对比](#13-参考实现对比) + +--- + +## 1. 设计目标与约束 + +### 1.1 核心目标 + +| 目标 | 说明 | +|------|------| +| **完整 HTTP 接口体系转换** | 覆盖 /models、/embeddings、/files、/rerank 等全部接口的 URL 路由映射、请求头转换、请求体/响应体格式转换 | +| **输入输出解耦** | 客户端协议和上游协议独立指定，任意组合 | +| **同协议透传** | source == target 时跳过转换，零语义损失、零序列化开销 | +| **尽力转换** | 能对接的参数尽可能对接，不能对接的各自忽略，保障最大覆盖面 | +| **协议可扩展** | 添加新协议只需实现 Adapter，不修改核心引擎 | +| **流式优先** | SSE 流式转换作为核心能力，与非流式同等地位 | +| **Tool Calling 核心** | 工具调用是编程场景的一等公民 | +| **语言无关** | 不绑定编程语言，用伪类型描述接口 | + +### 1.2 约束 + +| 约束 | 说明 | +|------|------| +| 部署形态 | HTTP 层 SDK，处理 HTTP 请求/响应转换（URL + Headers + Body），不包含 HTTP 服务器启动/监听 | +| 当前协议 | OpenAI API、Anthropic API | +| 当前模态 | 仅文本（含 Tool Calling），接口体系覆盖 /models、/count_tokens、/embeddings、/files、/rerank | +| Provider 必传 | 每次转换调用需传入 TargetProvider，提供目标上游的地址、认证、模型名等信息 | +| 适配器注册 | 所有 ProtocolAdapter 通过代码注册，不支持动态增减 | +| 有状态特性 | 初始不实现，架构预留扩展点 | + +### 1.3 设计决策溯源 + +| 决策 | 依据 | +|------|------| +| HTTP 层 SDK | 编程工具启动时调用 /models、/count_tokens 等接口，缺失会报错或功能降级 | +| Hub-and-Spoke | new-api 验证了以规范格式为枢纽的可行性，O(n²) 降为 O(n) | +| 自定义 Canonical Model | 不选用厂商格式，避免语义损失和厂商锁定 | +| 协议前缀路由 | CC-Switch 的 `/claude/`、`/codex/`、`/gemini/` 前缀验证了 URL 前缀区分协议的可行性 | +| 接口分层 + 尽力转换 | 不同接口差异程度不同，分层处理最大化覆盖面 | +| 同协议透传 | CC-Switch 的 Anthropic→Anthropic 直通验证了零转换性能优势 | + +--- + +## 2. 架构总览 + +### 2.1 分层架构 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 上层 HTTP 框架（用户自选） │ +│ Express / FastAPI / Axum / Gin / 任意框架 │ +└───────────────────────────────┬─────────────────────────────────────────┘ + │ HTTP 请求/响应 + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ Conversion Engine (SDK) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ Protocol Prefix Router │ │ +│ │ │ │ +│ │ 入站: /{protocol}/{native_path} │ │ +│ │ │ │ +│ │ /openai/v1/chat/completions → source=openai, CHAT │ │ +│ │ /anthropic/v1/messages → source=anthropic, CHAT │ │ +│ │ /openai/v1/models → source=openai, MODELS │ │ +│ │ /anthropic/v1/models → source=anthropic, MODELS │ │ +│ │ /openai/v1/* → source=openai, UNKNOWN │ │ +│ │ /anthropic/v1/* → source=anthropic, UNKNOWN │ │ +│ │ │ │ +│ │ Step 1: URL 前缀 → source protocol（唯一依据，无歧义） │ │ +│ │ Step 2: 剥离前缀 → 识别 InterfaceType │ │ +│ │ Step 3: target protocol 由配置决定 │ │ +│ └─────────────────────────────┬───────────────────────────────────┘ │ +│ │ │ +│ ┌────────────┼────────────┐ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────┐ ┌─────────┐ ┌──────────┐ │ +│ │ Passthrough │ │核心接口层│ │扩展接口层 │ │ +│ │ 同协议直通 │ │ Chat │ │ Models │ │ +│ │ 或未知接口 │ │ 流式 │ │ Embed │ │ +│ │ 直接转发 │ │ Tool │ │ Files │ │ +│ └──────────────┘ │ Thinking│ │ Rerank │ │ +│ └────┬────┘ └────┬─────┘ │ +│ ┌──────────▼──────────▼───────┐ │ +│ │ ProtocolAdapter 层 │ │ +│ │ ┌────────┐ ┌───────────┐ │ │ +│ │ │OpenAI │ │Anthropic │ │ │ +│ │ │Adapter │ │Adapter │ │ │ +│ │ └────────┘ └───────────┘ │ │ +│ └──────────────┬───────────────┘ │ +│ ┌──────────────▼───────────────┐ │ +│ │ Canonical Model │ │ +│ └──────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 URL 路由规则 + +入站 URL 采用协议前缀：`/{protocol}/{native_path}`。前缀是协议识别的**唯一依据**。 + +``` +入站 URL 剥离前缀后 出站（target=anthropic） +────────────────────────────────────────────────────────────────────────────────── +/openai/v1/chat/completions → /v1/chat/completions → /v1/messages +/anthropic/v1/messages → /v1/messages → /v1/chat/completions +/openai/v1/models → /v1/models → /v1/models +/anthropic/v1/models → /v1/models → /v1/models +/openai/v1/embeddings → /v1/embeddings → 不支持，透传或返回错误 +/anthropic/v1/messages/count_tokens→ /v1/messages/count_tokens→ OpenAI 无此接口 +``` + +协议前缀仅用于入站侧。出站到上游 API 时使用目标协议原生路径（无前缀）。 + +### 2.3 请求处理流程 + +每个 HTTP 请求的转换流程： + +``` +客户端入站 SDK 内部处理 上游出站 +┌──────────────────┐ ┌──────────────────┐ +│ URL: │ 1. 前缀提取: /anthropic/ → source=anthropic │ URL: │ +│ /anthropic/ │ 2. 前缀剥离: /v1/messages │ /v1/chat/ │ +│ v1/messages │ 3. 接口识别: CHAT │ completions │ +│ Headers: │ 4. 同协议? ──yes──▶ 剥离前缀后直接转发 │ Headers: │ +│ x-api-key │ └──no──▶ 继续转换 │ Authorization │ +│ Body: │ 5. URL 映射: /v1/messages → /v1/chat/completions │ Body: │ +│ {model,system, │ 6. Header 转换: x-api-key → Authorization: Bearer │ {model,messages,│ +│ messages,...} │ 7. Body 转换: Anthropic → Canonical → OpenAI │ tools,...} │ +└──────────────────┘ └──────────────────┘ +``` + +响应方向同理（含流式）。 + +**同协议透传**：source == target 时，仅剥离前缀后原样转发到上游。 +**未知接口透传**：无法识别的路径，URL+Header 适配后 Body 原样转发。 + +--- + +## 3. 接口体系分层 + +### 3.1 分层策略 + +| 层级 | 接口 | 转换方式 | +|------|------|---------| +| **核心层** | Chat Completions, Messages | Canonical Model 深度转换 | +| **扩展层** | /models, /embeddings, /files, /rerank, /count_tokens | 轻量级字段映射 | +| **透传层** | /batches, /fine-tuning, /audio/*, /images/*, /video/*, /moderations 等未知路径 | URL+Header 适配后 Body 原样转发 | + +**接口纳入原则**：只有 ≥2 个协议提供相同功能的接口才纳入转换层（核心层或扩展层），其余走透传。 + +**尽力转换策略**： +- 双方都支持且可映射 → 完整转换（如 /models） +- 目标协议不支持该接口 → 透传到上游或返回空响应/错误（可配置） +- 未知接口 → 始终透传 + +### 3.2 OpenAI 接口体系 + +``` +OpenAI API +├── /v1/chat/completions [核心层] +├── /v1/models [扩展层] +├── /v1/models/{model} [扩展层] +├── /v1/embeddings [扩展层] +├── /v1/files [扩展层] +├── /v1/files/{id}/content [扩展层] +├── /v1/rerank [扩展层] +├── /v1/batches [透传层] +├── /v1/fine_tuning/jobs [透传层] +├── /v1/audio/* [透传层] +├── /v1/images/* [透传层] +├── /v1/moderations [透传层] +├── /v1/realtime [透传层] +└── /v1/* [透传层] +``` + +### 3.3 Anthropic 接口体系 + +``` +Anthropic API +├── /v1/messages [核心层] +├── /v1/messages/count_tokens [扩展层] +├── /v1/models [扩展层] +├── /v1/batches [扩展层] +└── /v1/* [透传层] +``` + +--- + +## 4. Canonical Model（规范模型） + +协议无关的统一内部表示，Hub-and-Spoke 架构的枢纽。**核心层**使用完整 Canonical Model 深度转换；**扩展层**使用轻量 Canonical Models 做字段映射；**透传层**不使用。 + +设计原则：超集设计、类型化 discriminated union、前向兼容。Canonical Model 面向当前已适配协议（OpenAI、Anthropic）的公共语义进行抽象，字段随协议扩展演进（详见附录 D：字段晋升规范）。 + +### 4.1 CanonicalRequest + +``` +CanonicalRequest { + model: String + system: Union> + + SystemBlock { + text: String + } + + messages: Array + tools: Option> + tool_choice: Option + parameters: RequestParameters + thinking: Option + stream: Boolean + user_id: Option + output_format: Option + parallel_tool_use: Option // true = 允许并行, false = 禁止并行 +} +``` + +### 4.2 RequestParameters + +``` +RequestParameters { + max_tokens: Option + temperature: Option + top_p: Option + stop_sequences: Option> +} +``` + +### 4.3 CanonicalMessage / ContentBlock + +``` +CanonicalMessage { + role: Enum + content: Array +} + +ContentBlock = Union< + TextBlock, { type: "text", text: String } + ToolUseBlock, { type: "tool_use", id: String, name: String, input: Object } + ToolResultBlock, { type: "tool_result", tool_use_id: String, + content: Union>, + is_error: Option } + ThinkingBlock, { type: "thinking", thinking: String } + ImageBlock, { type: "image", source: ... } // 多模态预留 + AudioBlock, { type: "audio", source: ... } // 多模态预留 + VideoBlock, { type: "video", source: ... } // 多模态预留 + FileBlock { type: "file", source: ... } // 多模态预留 +> +``` + +### 4.4 CanonicalTool / ToolChoice + +``` +CanonicalTool { + name: String + description: Option + input_schema: Object +} + +ToolChoice = Union< + {type: "auto"}, + {type: "none"}, + {type: "any"}, + {type: "tool", name: String} +> +``` + +### 4.5 ThinkingConfig + +``` +ThinkingConfig { + type: Enum // Anthropic 启用时 budget_tokens 必填 + budget_tokens: Option // Anthropic: thinking tokens 不计入 max_tokens + effort: Option> // OpenAI +} +``` + +### 4.6 OutputFormat + +``` +OutputFormat = Union< + { type: "json_object" }, + { type: "json_schema", json_schema: { name: String, schema: Object, strict: Option } }, + { type: "text" } +> +``` + +### 4.7 CanonicalResponse + +``` +CanonicalResponse { + id: String + model: String + content: Array + stop_reason: Option // end_turn | max_tokens | tool_use | stop_sequence | content_filter + usage: CanonicalUsage +} + +CanonicalUsage { + input_tokens: Integer + output_tokens: Integer + cache_read_tokens: Option + cache_creation_tokens: Option + reasoning_tokens: Option +} +``` + +### 4.7 CanonicalStreamEvent + +采用 Anthropic 风格的类型化事件模型（比 OpenAI delta 模型语义更明确，双向转换更容易）： + +``` +CanonicalStreamEvent = Union< + MessageStartEvent, { type: "message_start", message: {id, model, usage} } + ContentBlockStartEvent, { type: "content_block_start", index, content_block } + ContentBlockDeltaEvent, { type: "content_block_delta", index, delta } + ContentBlockStopEvent, { type: "content_block_stop", index } + MessageDeltaEvent, { type: "message_delta", delta: {stop_reason}, usage } + MessageStopEvent, { type: "message_stop" } + ErrorEvent, { type: "error", error: {type, message} } + PingEvent { type: "ping" } +> + +content_block: Union< + {type: "text", text: ""}, + {type: "tool_use", id, name, input: {}}, + {type: "thinking", thinking: ""}, + {type: "image"} | {type: "audio"} | {type: "video"} // 预留 +> + +delta: Union< + {type: "text_delta", text}, + {type: "input_json_delta", partial_json}, + {type: "thinking_delta", thinking}, + {type: "image_delta", data} | {type: "audio_delta", data} // 预留 +> +``` + +### 4.8 扩展层 Canonical Models + +``` +// /models +CanonicalModelList { models: Array } +CanonicalModel { id, name, created, owned_by } + +// /embeddings +CanonicalEmbeddingRequest { model, input, encoding_format?, dimensions? } +CanonicalEmbeddingResponse { data: [{index, embedding}], model, usage } + +// /count_tokens +CanonicalTokenCountRequest { model, messages, system?, tools? } +CanonicalTokenCountResponse { input_tokens } + +// /files +CanonicalFileObject { id, object, filename?, bytes?, created_at?, purpose?, status? } + +// /rerank +CanonicalRerankRequest { model, query, documents, top_n?, return_documents? } +CanonicalRerankResponse { results: [{index, relevance_score, document?}], model } +``` + +### 4.9 设计说明 + +**`system` 为什么独立于 `messages`？** +Anthropic 用顶层 `system` 字段，OpenAI 用 `messages[role="system"]`。独立 `system` 语义更清晰，Decoder 提取、Encoder 注入。 + +**流式事件为什么用 Anthropic 风格？** +类型化事件有显式的 start/stop 生命周期，语义明确；OpenAI delta 模型需要状态机推断语义，双向转换更复杂。 + +**`user_id` 为什么从 `metadata` 中提升？** +OpenAI 用顶层 `user`，Anthropic 用 `metadata.user_id`。两者语义相同，提升为独立字段更清晰。 + +**`output_format` 为什么替代 `response_format`？** +OpenAI 的 `response_format` 和 Anthropic 新模型的 `output_format` 表达相同意图（控制输出格式），统一为 `output_format` 避免命名偏向。 + +**`parallel_tool_use` 为什么独立为顶层字段？** +OpenAI 用 `parallel_tool_calls`（允许），Anthropic 用 `disable_parallel_tool_use`（禁止），语义反转但表达相同控制。统一为正向语义。 + +--- + +## 5. Protocol Adapter 接口 + +### 5.1 TargetProvider + +每次转换调用传入的目标上游信息。Adapter 通过 Provider 获取认证和配置，**不需要理解其他协议的 Header 格式**。 + +``` +TargetProvider { + base_url: String // 上游 API 地址 + api_key: String // 上游认证密钥 + model_name: String // 目标模型名（调用方完成映射后传入） + adapter_config: Map // 协议专属配置（如 anthropic-version） +} +``` + +`adapter_config` 由各 Adapter 自行定义所需的 key，引擎不感知含义，原样透传。示例： +- Anthropic: `{ "anthropic_version": "2023-06-01", "anthropic_beta": ["..."] }` +- OpenAI: `{ "organization": "org-xxx" }` 或空 + +### 5.2 ProtocolAdapter + +每种协议的完整适配器，融入所有接口类型的处理能力。所有 Adapter 通过代码注册，不支持动态增减。 + +``` +interface ProtocolAdapter { + protocolName(): String + protocolVersion(): String + supportsPassthrough(): Boolean // 同协议透传开关，默认 true + + // HTTP 级别 + mapUrl(nativePath: String, interfaceType: InterfaceType): Option + buildHeaders(provider: TargetProvider): Map + supportsInterface(interfaceType: InterfaceType): Boolean + + // 核心层：Chat + decodeRequest(raw): CanonicalRequest + encodeRequest(canonical, provider): RawRequest + decodeResponse(raw): CanonicalResponse + encodeResponse(canonical): RawResponse + + // 核心层：流式 + createStreamDecoder(): StreamDecoder + createStreamEncoder(): StreamEncoder + + // 错误编码 + encodeError(error: ConversionError): RawResponse + + // 扩展层 + decodeModelsResponse(raw): CanonicalModelList + encodeModelsResponse(canonical): RawResponse + decodeEmbeddingRequest(raw): CanonicalEmbeddingRequest + encodeEmbeddingRequest(canonical, provider): RawRequest + decodeEmbeddingResponse(raw): CanonicalEmbeddingResponse + encodeEmbeddingResponse(canonical): RawResponse + decodeTokenCountRequest(raw): CanonicalTokenCountRequest + encodeTokenCountRequest(canonical, provider): RawRequest + decodeTokenCountResponse(raw): CanonicalTokenCountResponse + encodeTokenCountResponse(canonical): RawResponse + encodeFileListResponse(canonical): RawResponse + decodeRerankRequest(raw): CanonicalRerankRequest + encodeRerankRequest(canonical, provider): RawRequest + decodeRerankResponse(raw): CanonicalRerankResponse + encodeRerankResponse(canonical): RawResponse +} +``` + +**`buildHeaders` vs 原 `mapHeaders`**：Adapter 只需从 `provider` 中提取自己协议需要的认证和配置信息，构建自己的 Header 格式。不再需要理解其他协议的 Header。 + +### 5.3 InterfaceType + +``` +InterfaceType = Enum< + CHAT, MODELS, MODEL_INFO, EMBEDDINGS, FILES, RERANK, + COUNT_TOKENS, BATCHES, FINE_TUNING, + AUDIO, IMAGES, REALTIME, UNKNOWN +> +``` + +注：`MODERATIONS` 移除，仅 OpenAI 单协议支持，走透传层。 + +### 5.4 StreamDecoder / StreamEncoder + +``` +interface StreamDecoder { + processChunk(rawChunk): Array + flush(): Array +} + +interface StreamEncoder { + encodeEvent(event): Array + flush(): Array +} +``` + +### 5.5 AdapterRegistry + +``` +interface AdapterRegistry { + register(adapter: ProtocolAdapter): void + get(protocolName: String): ProtocolAdapter + listProtocols(): Array +} +``` + +协议识别规则：URL 第一个路径段即协议标识。 + +``` +/openai/v1/... → "openai" +/anthropic/v1/... → "anthropic" +/gemini/v1beta/... → "gemini" (未来) +未知前缀 → null, 上层框架自行处理 +``` + +--- + +## 6. Conversion Engine（转换引擎） + +### 6.1 ConversionEngine + +``` +class ConversionEngine { + registry: AdapterRegistry + middlewareChain: MiddlewareChain + + registerAdapter(adapter): void + use(middleware): void + + isPassthrough(source, target): Boolean { + return source == target && registry.get(source).supportsPassthrough() + } + + // 非流式请求转换 + convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest { + nativePath = stripProtocolPrefix(request.url) + interfaceType = detectInterfaceType(nativePath) + + if isPassthrough(sourceProtocol, targetProtocol): + targetAdapter = registry.get(targetProtocol) + return {url: provider.base_url + nativePath, method: request.method, + headers: targetAdapter.buildHeaders(provider), body: request.body} + + sourceAdapter = registry.get(sourceProtocol) + targetAdapter = registry.get(targetProtocol) + + targetUrl = targetAdapter.mapUrl(nativePath, interfaceType) ?? nativePath + targetHeaders = targetAdapter.buildHeaders(provider) + targetBody = convertBody(interfaceType, sourceAdapter, targetAdapter, provider, request.body) + + return {url: provider.base_url + targetUrl, method: request.method, + headers: targetHeaders, body: targetBody} + } + + // 非流式响应转换 + convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse { + if isPassthrough(sourceProtocol, targetProtocol): return response + + sourceAdapter = registry.get(sourceProtocol) + targetAdapter = registry.get(targetProtocol) + targetBody = convertResponseBody(interfaceType, sourceAdapter, targetAdapter, response.body) + + return {status: response.status, headers: response.headers, body: targetBody} + } + + // 流式转换 + createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter { + if isPassthrough(sourceProtocol, targetProtocol): + targetAdapter = registry.get(targetProtocol) + return new PassthroughStreamConverter(targetAdapter.buildHeaders(provider)) + + source = registry.get(sourceProtocol) + target = registry.get(targetProtocol) + return new CanonicalStreamConverter( + source.createStreamDecoder(), target.createStreamEncoder(), middlewareChain) + } +} +``` + +### 6.2 Body 转换分发 + +``` +function convertBody(interfaceType, sourceAdapter, targetAdapter, provider, body): + switch interfaceType: + case CHAT: + canonical = sourceAdapter.decodeRequest(body) + canonical = middlewareChain.apply(canonical) + return targetAdapter.encodeRequest(canonical, provider) + case MODELS: + return body // GET 请求，无 body + case EMBEDDINGS: + if !sourceAdapter.supportsInterface(EMBEDDINGS) + || !targetAdapter.supportsInterface(EMBEDDINGS): + return body // 尽力转换：不支持则透传 + return targetAdapter.encodeEmbeddingRequest( + sourceAdapter.decodeEmbeddingRequest(body), provider) + case RERANK: + // 同 EMBEDDINGS 模式 + case COUNT_TOKENS: + // 同 EMBEDDINGS 模式 + default: + return body // 透传层：原样转发 + +function convertResponseBody(interfaceType, sourceAdapter, targetAdapter, body): + // 结构与 convertBody 对称，CHAT 走 Canonical 深度转换，扩展层走轻量映射，默认透传 +``` + +### 6.3 StreamConverter + +``` +interface StreamConverter { + processChunk(rawChunk): Array + flush(): Array +} + +class PassthroughStreamConverter implements StreamConverter { + headers: Map + constructor(headers) { this.headers = headers } + processChunk(rawChunk): Array { return [rawChunk] } + flush(): Array { return [] } +} + +class CanonicalStreamConverter implements StreamConverter { + decoder: StreamDecoder + encoder: StreamEncoder + middleware: MiddlewareChain + + processChunk(rawChunk): + events = decoder.processChunk(rawChunk).map(e => middleware.applyStreamEvent(e)) + return events.flatMap(e => encoder.encodeEvent(e)) + + flush(): + return decoder.flush().flatMap(e => encoder.encodeEvent(e)) + encoder.flush() +} +``` + +### 6.4 Middleware + +引擎内部的拦截钩子，在 decode → encode 之间对 Canonical 进行变换。 + +``` +interface ConversionMiddleware { + intercept(canonical, sourceProtocol, targetProtocol, context): canonical | error + interceptStreamEvent?(event, sourceProtocol, targetProtocol, context): event | error +} + +ConversionContext { conversionId, interfaceType, timestamp, metadata } +``` + +- `intercept` 返回修改后的 canonical，或返回 ConversionError 以**中断转换** +- `interceptStreamEvent` 同理，返回错误可中断流式转换 +- 多个 Middleware 按注册顺序链式执行，任一中断则后续不再执行 + +### 6.5 使用示例 + +``` +engine = new ConversionEngine() +engine.registerAdapter(new OpenAIAdapter()) +engine.registerAdapter(new AnthropicAdapter()) + +// 场景1: OpenAI→Anthropic Chat +// 入站: /openai/v1/chat/completions +provider = TargetProvider { + base_url: "https://api.anthropic.com", + api_key: "sk-ant-xxx", + model_name: "claude-sonnet-4-20250514", + adapter_config: { "anthropic_version": "2023-06-01" } +} +out = engine.convertHttpRequest(inRequest, "openai", "anthropic", provider) +// 出站 /v1/messages, headers: x-api-key + anthropic-version + +// 场景2: /models 跨协议 +// 入站: /anthropic/v1/models +provider = TargetProvider { + base_url: "https://api.openai.com", + api_key: "sk-xxx", model_name: "", adapter_config: {} +} +out = engine.convertHttpRequest(inRequest, "anthropic", "openai", provider) +// source=anthropic, 出站 /v1/models + Authorization: Bearer + +// 场景3: 同协议透传 +// 入站: /openai/v1/chat/completions +provider = TargetProvider { + base_url: "https://api.openai.com", + api_key: "sk-xxx", model_name: "", adapter_config: {} +} +out = engine.convertHttpRequest(inRequest, "openai", "openai", provider) +// source=openai == target=openai → 剥离前缀, 用 provider 重建 headers 后原样转发 + +// 场景4: 流式转换 +converter = engine.createStreamConverter("anthropic", "openai", provider) +for chunk in upstreamSSE { + for out in converter.processChunk(chunk) { sendToClient(out) } +} +converter.flush() +``` + +--- + +## 7. 流式转换架构 + +### 7.1 转换管道 + +``` +上游 SSE 流 + │ + ├── 同协议: PassthroughStreamConverter（用 provider 重建 Headers 后逐块转发） + │ + └── 跨协议: CanonicalStreamConverter + StreamDecoder StreamEncoder + ┌───────────┐ ┌───────────┐ + │ SSE Parser│ │SSE Writer │ + └─────┬─────┘ └─────▲─────┘ + │ │ + ┌─────▼─────┐ CanonicalEvent[] ┌─────┴─────┐ + │ Event │──────────────────────▶│ Event │ + │ Translator │ ┌──────────┐ │ Translator │ + │ (状态机) │ │Middleware│ │ │ + └───────────┘ └──────────┘ └───────────┘ +``` + +### 7.2 StreamDecoder 状态 + +``` +StreamDecoderState { + messageStarted: Boolean + openBlocks: Set + currentBlockType: Map + currentBlockId: Map + toolCallIdMap: Map // OpenAI 特有 + toolCallNameMap: Map // OpenAI 特有 + toolCallArguments: Map // OpenAI 特有 + utf8Remainder: Option // UTF-8 跨 chunk 安全 + accumulatedUsage: Option +} +``` + +### 7.3 事件映射 + +**Anthropic SSE ↔ Canonical**：几乎 1:1 映射，事件类型完全对应。 + +**OpenAI SSE → Canonical**（需要状态机）： + +| OpenAI chunk | Canonical 事件 | +|---|---| +| 首个 chunk (id/model) | MessageStartEvent | +| delta.content 首次 | ContentBlockStart(text) + ContentBlockDelta(text_delta) | +| delta.content 后续 | ContentBlockDelta(text_delta) | +| delta.tool_calls[i] 首次 | ContentBlockStart(tool_use) | +| delta.tool_calls[i].arguments | ContentBlockDelta(input_json_delta) | +| delta.reasoning_content | ContentBlockStart(thinking) + ContentBlockDelta(thinking_delta) | +| finish_reason | ContentBlockStop × N + MessageDeltaEvent + MessageStopEvent | +| [DONE] | flush() | + +**Canonical → OpenAI SSE**（Encoder 端）： + +| Canonical 事件 | OpenAI chunk | +|---|---| +| MessageStartEvent | 首个 chunk (id, model, delta:{}) | +| ContentBlockStart(text) | 缓冲，不输出 | +| ContentBlockDelta(text) | {choices:[{delta:{content:"..."}}]}（首次合并 block_start） | +| ContentBlockStart(tool) | 缓冲 | +| ContentBlockDelta(input_json) | {choices:[{delta:{tool_calls:[...]}}]}（首次含 id/name） | +| ContentBlockStop | 不输出 | +| MessageDeltaEvent | {choices:[{finish_reason:"..."}]} | +| MessageStopEvent | [DONE] | +| PingEvent | 丢弃 | + +--- + +## 8. OpenAI 协议适配器 + +### 8.1 URL 路径映射 + +``` +OpenAI.mapUrl(nativePath, interfaceType): + switch interfaceType: + case CHAT: return "/v1/chat/completions" + case MODELS: return "/v1/models" + case MODEL_INFO: return "/v1/models/{modelId}" + case EMBEDDINGS: return "/v1/embeddings" + case FILES: return nativePath + case RERANK: return "/v1/rerank" + default: return nativePath +``` + +### 8.2 请求头构建 + +``` +OpenAI.buildHeaders(provider): + result = {} + result["Authorization"] = "Bearer " + provider.api_key + if provider.adapter_config["organization"]: + result["OpenAI-Organization"] = provider.adapter_config["organization"] + result["Content-Type"] = "application/json" + return result +``` + +### 8.3 接口能力声明 + +``` +OpenAI.supportsInterface(type): + CHAT...IMAGES: return true // 全部支持 + COUNT_TOKENS: return false // OpenAI 无此接口 + default: return false +``` + +### 8.4 Chat 请求 Decoder/Encoder + +#### Decoder: decodeRequest → CanonicalRequest + +``` +decodeSystemPrompt(messages): + systemMsgs = messages.filter(m => m.role == "system") + remaining = messages.filter(m => m.role != "system") + if systemMsgs.length == 0: return {system: None, messages: remaining} + return {system: systemMsgs.map(m => extractText(m.content)).join("\n\n"), messages: remaining} +``` + +``` +decodeMessage(msg): + switch msg.role: + case "user": + return {role: "user", content: decodeUserContent(msg.content)} + case "assistant": + blocks = [] + if msg.content: blocks.append({type: "text", text: extractText(msg.content)}) + if msg.refusal: blocks.append({type: "text", text: msg.refusal}) + if msg.tool_calls: + for tc in msg.tool_calls: + blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, + input: JSON.parse(tc.function.arguments)}) + return {role: "assistant", content: blocks} + case "tool": + return {role: "tool", content: [{ + type: "tool_result", tool_use_id: msg.tool_call_id, + content: msg.content, is_error: false}]} +``` + +#### Encoder: encodeRequest ← CanonicalRequest + +``` +encodeRequest(canonical, provider): + result = { + model: provider.model_name, + messages: encodeSystemPrompt(canonical) + canonical.messages.flatMap(encodeMessage), + max_tokens: canonical.parameters.max_tokens, + temperature: canonical.parameters.temperature, + top_p: canonical.parameters.top_p, + stream: canonical.stream + } + if canonical.parameters.stop_sequences: + result.stop = canonical.parameters.stop_sequences + if canonical.user_id: + result.user = canonical.user_id + if canonical.output_format: + result.response_format = encodeOutputFormat(canonical.output_format) + if canonical.parallel_tool_use != null: + result.parallel_tool_calls = canonical.parallel_tool_use + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + type: "function", function: {name: t.name, description: t.description, parameters: t.input_schema}})) + if canonical.tool_choice: + result.tool_choice = encodeToolChoice(canonical.tool_choice) + if canonical.thinking && canonical.thinking.type == "enabled": + result.reasoning_effort = canonical.thinking.effort ?? "medium" + return result + +encodeOutputFormat(format): + switch format.type: + "json_object" → {type: "json_object"} + "json_schema" → {type: "json_schema", json_schema: format.json_schema} + "text" → null + +encodeToolChoice(choice): + switch choice.type: + "auto" → "auto" + "none" → "none" + "any" → "required" + "tool" → {type: "function", function: {name: choice.name}} + +``` + +### 8.5 Chat 响应 Decoder/Encoder + +``` +// Decoder +mapStopReason(reason): + "stop" → "end_turn" | "length" → "max_tokens" | "tool_calls" → "tool_use" | "content_filter" → "content_filter" | _ → "end_turn" + +decodeResponse(openaiResp): + choice = openaiResp.choices[0] + blocks = [] + if choice.message.content: blocks.append({type: "text", text: choice.message.content}) + if choice.message.refusal: blocks.append({type: "text", text: choice.message.refusal}) + if choice.message.reasoning_content: + blocks.append({type: "thinking", thinking: choice.message.reasoning_content}) + if choice.message.tool_calls: + for tc: blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, + input: JSON.parse(tc.function.arguments)}) + return CanonicalResponse {id, model, content: blocks, stop_reason: mapStopReason(choice.finish_reason), usage: decodeUsage(openaiResp.usage)} + +// Encoder +mapCanonicalToFinishReason(reason): + "end_turn" → "stop" | "max_tokens" → "length" | "tool_use" → "tool_calls" | "content_filter" → "content_filter" | _ → "stop" + +encodeResponse(canonical): + textParts = canonical.content.filter(b => b.type == "text") + toolUses = canonical.content.filter(b => b.type == "tool_use") + message = {} + if textParts.length > 0: message.content = textParts.map(b => b.text).join("") + elif toolUses.length > 0: message.content = null + else: message.content = "" + if toolUses.length > 0: + message.tool_calls = toolUses.map(tu => ({ + id: tu.id, type: "function", + function: {name: tu.name, arguments: JSON.stringify(tu.input)}})) + return {id: canonical.id, object: "chat.completion", model: canonical.model, + choices: [{index: 0, message, finish_reason: mapCanonicalToFinishReason(canonical.stop_reason)}], + usage: encodeUsage(canonical.usage)} +``` + +### 8.6 /models 响应编解码 + +``` +// Decoder: OpenAI → Canonical +decodeModelsResponse(openaiResp): + return CanonicalModelList { + models: openaiResp.data.map(m => CanonicalModel { + id: m.id, name: m.id, created: m.created, owned_by: m.owned_by })} + +// Encoder: Canonical → OpenAI +encodeModelsResponse(canonical): + return {object: "list", + data: canonical.models.map(m => ({id: m.id, object: "model", + created: m.created ?? 0, owned_by: m.owned_by ?? "unknown"}))} +``` + +**跨协议示例（入站 `/openai/v1/models`，目标 Anthropic）**： + +``` +入站: GET /openai/v1/models, Authorization: Bearer sk-xxx + → source=openai, target=anthropic + → URL: /v1/models, Headers: x-api-key: sk-xxx, anthropic-version: ... + +Anthropic 上游响应: {data: [{id: "claude-sonnet-4", display_name: "Claude Sonnet 4", ...}], has_more: false} + → Anthropic.decodeModelsResponse → CanonicalModelList + → OpenAI.encodeModelsResponse + +返回客户端: {object: "list", data: [{id: "claude-sonnet-4", object: "model", created: 0, owned_by: "anthropic"}]} +``` + +--- + +## 9. Anthropic 协议适配器 + +### 9.1 URL 路径映射 + +``` +Anthropic.mapUrl(nativePath, interfaceType): + switch interfaceType: + case CHAT: return "/v1/messages" + case MODELS: return "/v1/models" + case MODEL_INFO: return "/v1/models/{modelId}" + case COUNT_TOKENS: return "/v1/messages/count_tokens" + case EMBEDDINGS: return null // 不支持 + case RERANK: return null + case FILES: return null + default: return nativePath +``` + +### 9.2 请求头构建 + +``` +Anthropic.buildHeaders(provider): + result = {} + result["x-api-key"] = provider.api_key + result["anthropic-version"] = provider.adapter_config["anthropic_version"] ?? "2023-06-01" + if provider.adapter_config["anthropic_beta"]: + result["anthropic-beta"] = provider.adapter_config["anthropic_beta"].join(",") + result["Content-Type"] = "application/json" + return result +``` + +### 9.3 接口能力声明 + +``` +Anthropic.supportsInterface(type): + CHAT: return true + MODELS: return true + COUNT_TOKENS: return true + BATCHES: return true + default: return false +``` + +### 9.4 Chat 请求 Decoder/Encoder + +#### Decoder + +``` +decodeSystem(system): + if system is None: return None + if system is String: return system + return system.map(s => SystemBlock {text: s.text}) + +decodeMessage(msg): + switch msg.role: + case "user": + blocks = decodeContentBlocks(msg.content) + toolResults = blocks.filter(b => b.type == "tool_result") + others = blocks.filter(b => b.type != "tool_result") + if toolResults.length > 0: + return [ + ...(others.length > 0 ? [{role: "user", content: others}] : []), + {role: "tool", content: toolResults}] + return [{role: "user", content: blocks}] + case "assistant": + return [{role: "assistant", content: decodeContentBlocks(msg.content)}] + +decodeContentBlocks(content): + if content is String: return [{type: "text", text: content}] + return content.map(block => { + switch block.type: + "text" → TextBlock{text: block.text} + "tool_use" → ToolUseBlock{id: block.id, name: block.name, input: block.input} + "tool_result" → ToolResultBlock{tool_use_id: block.tool_use_id, ...} + "thinking" → ThinkingBlock{thinking: block.thinking} + "redacted_thinking" → 丢弃 }) // 仅 Anthropic 使用，不在中间层保留 + +// 额外字段提取 +decodeExtras(raw): + user_id = raw.metadata?.user_id + output_format = null // Anthropic 旧模型无 output_format，新模型通过 output_config 提取 + parallel_tool_use = raw.disable_parallel_tool_use == true ? false : null + thinking = raw.thinking ? ThinkingConfig { + type: raw.thinking.type, // "enabled" | "disabled" + budget_tokens: raw.thinking.budget_tokens, + effort: null } : null +``` + +#### Encoder + +``` +encodeRequest(canonical, provider): + result = { + model: provider.model_name, + messages: encodeMessages(canonical), + max_tokens: canonical.parameters.max_tokens, + temperature: canonical.parameters.temperature, + top_p: canonical.parameters.top_p, + stream: canonical.stream + } + if canonical.system: + result.system = encodeSystem(canonical.system) + if canonical.parameters.stop_sequences: + result.stop_sequences = canonical.parameters.stop_sequences + if canonical.user_id: + result.metadata = {user_id: canonical.user_id} + if canonical.output_format: + result.output_format = encodeOutputFormat(canonical.output_format) + if canonical.parallel_tool_use == false: + result.disable_parallel_tool_use = true + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + name: t.name, description: t.description, input_schema: t.input_schema})) + if canonical.tool_choice: + result.tool_choice = encodeToolChoice(canonical.tool_choice) + if canonical.thinking: + result.thinking = {type: canonical.thinking.type} + if canonical.thinking.budget_tokens: + result.thinking.budget_tokens = canonical.thinking.budget_tokens + return result + +encodeSystem(system): + if system is String: return system + return system.map(s => ({text: s.text})) + +encodeToolChoice(choice): + switch choice.type: + "auto" → {type: "auto"} + "none" → {type: "none"} + "any" → {type: "any"} + "tool" → {type: "tool", name: choice.name} +``` + +### 9.5 Chat 响应 Decoder/Encoder + +``` +// Decoder +decodeResponse(anthropicResp): + blocks = [] + for block in anthropicResp.content: + switch block.type: + "text" → blocks.append({type: "text", text: block.text}) + "tool_use" → blocks.append({type: "tool_use", id: block.id, name: block.name, input: block.input}) + "thinking" → blocks.append({type: "thinking", thinking: block.thinking}) + "redacted_thinking" → 丢弃 // 仅 Anthropic 使用，不在中间层保留 + return CanonicalResponse {id, model, content: blocks, stop_reason: anthropicResp.stop_reason, + usage: CanonicalUsage {input_tokens, output_tokens, + cache_read_tokens: anthropicResp.usage.cache_read_input_tokens, + cache_creation_tokens: anthropicResp.usage.cache_creation_input_tokens}} + +// Encoder +encodeResponse(canonical): + blocks = canonical.content.map(block => { + switch block.type: + "text" → {type: "text", text: block.text} + "tool_use" → {type: "tool_use", id: block.id, name: block.name, input: block.input} + "thinking" → {type: "thinking", thinking: block.thinking}}) + return {id: canonical.id, type: "message", role: "assistant", model: canonical.model, + content: blocks, + stop_reason: canonical.stop_reason == "content_filter" ? "end_turn" : canonical.stop_reason, + stop_sequence: None, + usage: {input_tokens: canonical.usage.input_tokens, output_tokens: canonical.usage.output_tokens, + cache_read_input_tokens: canonical.usage.cache_read_tokens, + cache_creation_input_tokens: canonical.usage.cache_creation_tokens}} + +// 错误编码 +encodeError(error): + return {type: "error", error: {type: error.code, message: error.message}} +``` + +### 9.6 /models 响应编解码 + +``` +// Decoder: Anthropic → Canonical +decodeModelsResponse(anthropicResp): + return CanonicalModelList { + models: anthropicResp.data.map(m => CanonicalModel { + id: m.id, name: m.display_name ?? m.id, created: m.created_at, + owned_by: "anthropic"})} + +// Encoder: Canonical → Anthropic +encodeModelsResponse(canonical): + return {data: canonical.models.map(m => ({ + id: m.id, + display_name: m.name ?? m.id, + created_at: m.created ?? 0, type: "model"})), + has_more: false, + first_id: canonical.models[0]?.id, last_id: canonical.models.last?.id} +``` + +### 9.7 /count_tokens 编解码 + +``` +// Decoder +decodeTokenCountRequest(raw): + return CanonicalTokenCountRequest { + model: raw.model, messages: decodeMessages(raw.messages), + system: decodeSystem(raw.system), tools: decodeTools(raw.tools)} + +// Encoder +encodeTokenCountRequest(canonical): + return {model: canonical.model, messages: encodeMessages(canonical), + system: encodeSystem(canonical), tools: encodeTools(canonical.tools)} + +decodeTokenCountResponse(raw): + return CanonicalTokenCountResponse {input_tokens: raw.input_tokens} + +encodeTokenCountResponse(canonical): + return {input_tokens: canonical.input_tokens} +``` + +**跨协议对接策略（入站 `/anthropic/v1/messages/count_tokens`，目标 OpenAI）**： + +OpenAI 不提供 `/count_tokens` 接口。Anthropic Claude Code 启动时会调用此接口。 + +| 策略 | 实现 | +|------|------| +| **透传** | URL+Header 适配后发送到 OpenAI，由上游返回 404 | +| **模拟（推荐）** | 解码请求，用估算器返回近似 token 数 | +| **精确估算** | 解码 messages，调用 OpenAI Chat Completions (max_tokens=1)，从 usage.prompt_tokens 获取 | + +策略选择通过配置或 Middleware 决定。 + +--- + +## 10. 字段映射参考 + +### 10.1 Chat 请求字段映射 + +| Canonical | OpenAI | Anthropic | 说明 | +|---|---|---|---| +| `system` | `messages[0].role="system"` | `system` (顶层) | 位置差异 | +| `user_id` | `user` (顶层) | `metadata.user_id` | 嵌套差异 | +| `output_format` | `response_format` | `output_format` (新模型) | 字段名差异；旧 Anthropic 模型需降级 | +| `parallel_tool_use` | `parallel_tool_calls` (bool) | `disable_parallel_tool_use` (bool, 反转) | 语义反转 | +| `ToolUseBlock` | `tool_calls[{id,function}]` | `content[{type:"tool_use"}]` | OpenAI 在 message 顶层 | +| `ToolResultBlock` | `{role:"tool",tool_call_id}` | `content[{type:"tool_result"}]` in user | 结构性差异 | +| `tools[].input_schema` | `tools[].function.parameters` | `tools[].input_schema` | 字段名不同 | +| `tool_choice: "any"` | `"required"` | `{type:"any"}` | 语义映射 | +| `max_tokens` | `max_tokens` / `max_completion_tokens` | `max_tokens` | o-series 差异 | +| `stop_sequences` | `stop` (String or Array) | `stop_sequences` (Array) | OpenAI Decoder 规范化为 Array | +| `thinking.type` | — | `thinking.type` | Anthropic 特有 | +| `thinking.effort` | `reasoning_effort` | — | OpenAI 参数级 | +| `thinking.budget_tokens` | — | `thinking.budget_tokens` | Anthropic token 级 | + +### 10.2 Chat 响应字段映射 + +| Canonical | OpenAI | Anthropic | +|---|---|---| +| `stop_reason: "end_turn"` | `finish_reason: "stop"` | `stop_reason: "end_turn"` | +| `stop_reason: "max_tokens"` | `finish_reason: "length"` | `stop_reason: "max_tokens"` | +| `stop_reason: "tool_use"` | `finish_reason: "tool_calls"` | `stop_reason: "tool_use"` | +| `ThinkingBlock` | `reasoning_content` (非流式) | `content[{type:"thinking"}]` | +| `usage.input_tokens` | `usage.prompt_tokens` | `usage.input_tokens` | +| `usage.output_tokens` | `usage.completion_tokens` | `usage.output_tokens` | +| `usage.cache_read_tokens` | `usage.prompt_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` | + +### 10.3 HTTP 头映射 + +Headers 由各 Adapter 的 `buildHeaders(provider)` 方法构建，从 `provider.api_key` 和 `provider.adapter_config` 获取信息，无需理解其他协议。 + +| 场景 | OpenAI | Anthropic | +|------|--------|-----------| +| 认证 | `Authorization: Bearer ` | `x-api-key: ` | +| 版本 | — | `anthropic-version`（从 adapter_config 读取） | +| Beta | — | `anthropic-beta`（从 adapter_config 读取） | + +### 10.4 扩展层接口映射 + +#### /models + +| 维度 | OpenAI | Anthropic | +|------|--------|-----------| +| 响应格式 | `{object:"list", data:[{id, object:"model", created, owned_by}]}` | `{data:[{id, display_name, created_at, type}], has_more, first_id, last_id}` | +| 映射 | `id↔id`, `created↔created_at`, `owned_by→"anthropic"`, `display_name→id` | + +#### /count_tokens + +| 维度 | OpenAI | Anthropic | +|------|--------|-----------| +| 存在性 | 不存在 | `POST /v1/messages/count_tokens` | +| 策略 | Anthropic→OpenAI: 模拟/估算 | 原生支持 | + +#### /embeddings + +| 维度 | OpenAI | Anthropic | +|------|--------|-----------| +| 存在性 | `POST /v1/embeddings` | 不存在 | +| 策略 | 原生支持 | OpenAI→Anthropic: 返回不支持错误 | + +--- + +## 11. 扩展点设计 + +### 11.1 新协议接入 + +1. 实现 ProtocolAdapter（URL 映射 + Header 映射 + 各接口编解码） +2. 注册到 AdapterRegistry +3. 完成 + +### 11.2 多模态扩展 + +Canonical Model 已预留 ImageBlock / AudioBlock / VideoBlock / FileBlock。实现路径： +1. 在各 ProtocolAdapter 中实现多模态块的编解码 +2. 在 StreamDecoder/StreamEncoder 中处理多模态增量数据 + +### 11.3 有状态特性扩展 + +``` +interface StatefulMiddleware extends ConversionMiddleware { + stateStore: SessionStateStore +} +``` + +适用场景：Gemini thoughtSignature 跨轮次保留。 + +### 11.4 特性降级策略 + +| 源特性 | 目标协议 | 降级方式 | +|--------|---------|---------| +| `output_format` | Anthropic（旧模型） | 注入合成工具实现 JSON 模式 | +| `thinking.effort` | Anthropic | 转为 `thinking.budget_tokens` | +| `thinking.budget_tokens` | OpenAI | 转为 `reasoning_effort` | +| `count_tokens` | OpenAI | 模拟/估算 | +| `/embeddings` | Anthropic | 返回不支持的错误 | + +### 11.5 自定义接口支持 + +``` +interface CustomInterfaceHandler { + interfaceType(): InterfaceType + matchUrl(url): Boolean + convertRequest(source, target, raw): raw + convertResponse(source, target, raw): raw +} +engine.registerCustomHandler(handler) +``` + +--- + +## 12. 错误处理 + +### 12.1 错误分类 + +``` +ConversionError { code: ErrorCode, message, sourceProtocol?, targetProtocol?, + interfaceType?, details?, cause? } + +ErrorCode = Enum< + INVALID_INPUT, // 请求格式不符合协议规范 + MISSING_REQUIRED_FIELD, // 缺少必填字段 + INCOMPATIBLE_FEATURE, // 特性在目标协议不可用 + FIELD_MAPPING_FAILURE, // 字段映射逻辑错误 + TOOL_CALL_PARSE_ERROR, // 工具调用参数解析失败 + JSON_PARSE_ERROR, // JSON 解析失败 + STREAM_STATE_ERROR, // 流式状态机异常 + UTF8_DECODE_ERROR, // UTF-8 解码错误 + PROTOCOL_CONSTRAINT_VIOLATION, // 违反协议约束 + ENCODING_FAILURE, // 编码失败 + INTERFACE_NOT_SUPPORTED // 目标协议不支持此接口 +> +``` + +### 12.2 错误处理策略 + +``` +ErrorHandler { mode: "strict" | "lenient" } + +strict: 任何错误抛出异常 +lenient: 尽力继续 + INCOMPATIBLE_FEATURE → 降级继续 + INTERFACE_NOT_SUPPORTED → 透传或返回空响应 + TOOL_CALL_PARSE_ERROR → 保留原始内容继续 + PROTOCOL_CONSTRAINT_VIOLATION → 自动修复 +``` + +**不支持接口的处理**（`INTERFACE_NOT_SUPPORTED`）： + +| 策略 | 适用场景 | 实现 | +|------|---------|------| +| 透传 | 上游可能有自己的实现 | URL+Header 适配后 Body 原样转发 | +| 返回空响应 | 不影响核心功能 | 返回空列表 `{data: []}` | +| 返回错误 | 客户端明确需要此功能 | 返回 501 或协议格式错误 | + +具体策略通过配置或 Middleware 决定。 + +### 12.3 错误响应格式 + +转换失败时，错误响应用**客户端协议（source protocol）**的格式编码。由 `sourceAdapter.encodeError(error)` 完成： + +- OpenAI 格式：`{error: {message, type, code, param}}` +- Anthropic 格式：`{type: "error", error: {type, message}}` + +Middleware 中断转换时同理，引擎调用 sourceAdapter.encodeError 将 ConversionError 编码为客户端可理解的格式。 + +--- + +## 13. 参考实现对比 + +### 13.1 关键差异 + +| 维度 | CC-Switch | LiteLLM | new-api | one-api | 本设计 | +|------|-----------|---------|---------|---------|--------| +| 定位 | 桌面代理 | 完整网关+SDK | 完整网关 | 完整网关 | HTTP 层 SDK | +| 架构 | 直接转换 | 策略+工厂 | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (自定义) | +| 转换方向 | 双向(有限) | 单向→厂商 | 单向→OpenAI | 单向→OpenAI | 双向(任意协议对) | +| Canonical 模型 | 无 | 无 | OpenAI 格式 | OpenAI 格式 | 自定义超集，字段随协议扩展演进 | +| 厂商覆盖 | 2 | 100+ | 50+ | 56 渠道/19 API 类型 | 协议级(当前 2, 可扩展) | +| 管理接口 | /health, /status | 全接口 | 全接口 | 全接口 | /models, /embeddings, /count_tokens, /files, /rerank + 透传层 | +| 同协议透传 | Anthropic 直通 | 无 | 开关控制 | OpenAI 兼容渠道零拷贝 | 自动检测 | +| 协议前缀 | /claude/, /codex/, /gemini/ | 无 | 无 | 无 | /openai/, /anthropic/ | +| 流式处理 | 简单转发 | 简单解析 | Scanner+SSE | Scanner+SSE | StreamDecoder/Encoder 状态机 | +| 错误处理 | 基础 | 基础 | 统一格式归一化 | 多格式归一化 | strict/lenient 模式 + ErrorCode 枚举 | +| 扩展机制 | 硬编码 | 策略模式 | 实现 Adaptor 接口 | 实现 Adaptor 接口 | ProtocolAdapter + Middleware + 自定义接口 | + +### 13.2 设计取舍 + +| 取舍 | 选择 | 理由 | +|------|------|------| +| HTTP 层 SDK vs 纯 chat 库 | HTTP 层 SDK | 编程工具需要管理接口 | +| 自定义 Canonical vs OpenAI | 自定义 | 避免厂商锁定 | +| 接口分层 vs 全部深度转换 | 分层 | 核心深度转换，扩展轻量映射，透传零转换 | +| 尽力转换 vs 严格转换 | 尽力转换 | 最大化覆盖面 | +| 透传 vs 总是 Canonical | 自动透传 + 可选禁用 | 同协议和未知接口的性能优化 | + +### 13.3 关键经验 + +- **CC-Switch**: UTF-8 跨 chunk 截断处理必要；工具调用参数可能乱序到达；同协议直通是最高频路径 +- **LiteLLM**: BaseConfig 抽象 + 编排器不变模式扩展性好；全接口覆盖对用户体验至关重要 +- **new-api**: 多格式输入的 Hub-and-Spoke 已生产验证；/models 的协议感知转换价值最高 +- **one-api**: 以 OpenAI 格式为 Canonical 的 Hub-and-Spoke 架构在 19 种 API 类型、56 个渠道的生产环境验证了可行性；大量厂商(DepSeek/Groq/Mistral/Moonshot 等)采用 OpenAI 兼容格式使得同协议透传成为最高频路径；适配器模式的 ChannelType→APIType→Adaptor 三层映射提供了厂商级精细控制但增加了维护复杂度 + +--- + +## 附录 A：完整转换流程示例 + +``` +客户端发送: +POST /openai/v1/chat/completions HTTP/1.1 ← /openai/ 前缀标识源协议 +Authorization: Bearer sk-xxx +Content-Type: application/json + +{ "model": "gpt-4", + "messages": [ + {"role": "system", "content": "You are a coding assistant"}, + {"role": "user", "content": "Read the file main.py"}, + {"role": "assistant", "content": null, "tool_calls": [{ + "id": "call_abc123", "type": "function", + "function": {"name": "read_file", "arguments": "{\"path\": \"main.py\"}"}}]}, + {"role": "tool", "tool_call_id": "call_abc123", "content": "print('hello')"}, + {"role": "user", "content": "What does this code do?"}], + "tools": [{"type": "function", "function": {"name": "read_file", "parameters": {...}}}], + "max_tokens": 1024, "stream": true } + + │ + ▼ + +engine.convertHttpRequest(request, "openai", "anthropic", provider) + +provider = TargetProvider { + base_url: "https://api.anthropic.com", + api_key: "sk-ant-xxx", + model_name: "claude-sonnet-4-20250514", + adapter_config: { "anthropic_version": "2023-06-01" } +} + +Step 0: 前缀 /openai/ → source=openai, 剥离后 /v1/chat/completions +Step 1: 接口识别 → CHAT +Step 2: URL 映射 → /v1/messages +Step 3: Header 构建 → x-api-key: sk-ant-xxx, anthropic-version: 2023-06-01 +Step 4: Body 转换: + + OpenAI.decodeRequest → CanonicalRequest { + model: "gpt-4", + system: "You are a coding assistant", + messages: [ + {user, [{text, "Read the file main.py"}]}, + {assistant, [{tool_use, id:"call_abc123", name:"read_file", input:{path:"main.py"}}]}, + {tool, [{tool_result, tool_use_id:"call_abc123", content:"print('hello')"}]}, + {user, [{text, "What does this code do?"}]}], + parameters: {max_tokens: 1024}, + stream: true } + + Anthropic.encodeRequest(canonical, provider) → { + "model": "claude-sonnet-4-20250514", ← 使用 provider.model_name + "system": "You are a coding assistant", + "messages": [ + {"role": "user", "content": [{"type": "text", "text": "Read the file main.py"}]}, + {"role": "assistant", "content": [{"type": "tool_use", "id": "call_abc123", ...}]}, + {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_abc123", ...}]}, + {"role": "user", "content": [{"type": "text", "text": "What does this code do?"}]}], + "max_tokens": 1024, "stream": true } + +发往 Anthropic 上游: +POST https://api.anthropic.com/v1/messages HTTP/1.1 ← provider.base_url + 目标路径 +x-api-key: sk-ant-xxx +anthropic-version: 2023-06-01 +``` + +--- + +## 附录 B：模块依赖 + +``` +┌──────────────────────────────────────────────────┐ +│ ConversionEngine │ +│ 门面：HTTP 转换 / 协议路由 / 透传判断 / 流式转换 │ +│ ┌────────────────────────────────────────────┐ │ +│ │ Protocol Prefix Router │ │ +│ │ URL 前缀 → source protocol │ │ +│ └────────────────────────────────────────────┘ │ +├──────────────────────────────────────────────────┤ +│ TargetProvider │ +│ base_url / api_key / model_name / adapter_config │ +├──────────────────┬───────────────────────────────┤ +│ AdapterRegistry │ MiddlewareChain │ +├──────────────────┴───────────────────────────────┤ +│ StreamConverter: Passthrough | Canonical │ +├──────────────────────────────────────────────────┤ +│ ProtocolAdapter: OpenAI | Anthropic | Future... │ +│ · buildHeaders(provider) · URL 映射 │ +│ · Chat/Models/Embeddings/Rerank/... 编解码 │ +│ · encodeError · StreamDecoder / StreamEncoder │ +├──────────────────────────────────────────────────┤ +│ Canonical Model (Core + Extended) │ +├──────────────────────────────────────────────────┤ +│ Error Handling │ +├──────────────────────────────────────────────────┤ +│ Utility: UTF-8 Buffer / SSE Parser / Detector │ +└──────────────────────────────────────────────────┘ +``` + +--- + +## 附录 C：接口速查 + +``` +// ─── 核心入口 ─── +ConversionEngine + .registerAdapter(adapter) + .use(middleware) + .isPassthrough(source, target): Boolean + .convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest + .convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse + .createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter + +// ─── 目标上游信息 ─── +TargetProvider + .base_url: String + .api_key: String + .model_name: String + .adapter_config: Map + +// ─── URL 路由 ─── +// 入站: /{protocol}/{native_path} +// /openai/v1/chat/completions → source=openai +// /anthropic/v1/messages → source=anthropic +// 出站: provider.base_url + 目标协议原生路径（无前缀） + +// ─── 协议适配器 ─── +ProtocolAdapter + .protocolName() / .protocolVersion() / .supportsPassthrough() + .mapUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type) + .decodeRequest(raw) / .encodeRequest(canonical, provider) + .decodeResponse(raw) / .encodeResponse(canonical) + .createStreamDecoder() / .createStreamEncoder() + .encodeError(error): RawResponse + .decodeModelsResponse / .encodeModelsResponse + .decodeEmbeddingRequest / .encodeEmbeddingRequest(canonical, provider) / ...Response + .decodeTokenCountRequest / .encodeTokenCountRequest(canonical, provider) / ...Response + .decodeRerankRequest / .encodeRerankRequest(canonical, provider) / ...Response + +// ─── 流式处理 ─── +StreamConverter: .processChunk(raw) / .flush() + ├─ PassthroughStreamConverter [raw] → [raw]（用 provider 重建 Headers） + └─ CanonicalStreamConverter decode → middleware → encode + +// ─── 接口类型 ─── +InterfaceType = CHAT | MODELS | MODEL_INFO | EMBEDDINGS | FILES | + RERANK | COUNT_TOKENS | BATCHES | + FINE_TUNING | AUDIO | IMAGES | REALTIME | UNKNOWN +``` + +--- + +## 附录 D：字段晋升规范 + +### 原则 + +Canonical Model 是**活的公共契约**，不是固定不变的。其字段集反映的是**当前已适配协议的公共语义**，随协议扩展而演进。 + +### 字段分类 + +| 分类 | 判定条件 | 处理方式 | +|------|---------|---------| +| **公共字段** | ≥2 个协议表达相同含义 | 升级为 Canonical Model 的正式字段 | +| **协议特有字段** | 仅 1 个协议使用 | 不在中间层传播；同协议透传时自然保留；跨协议时丢弃 | +| **未知字段** | 新协议带来的新概念 | 先按特有字段处理；当第二个协议也出现时晋升 | + +### 晋升流程 + +``` +1. 发现：适配新协议时，识别出无法映射到现有 Canonical 字段的语义 +2. 判定：该语义是否已被 ≥1 个现有协议所表达？ + - 是 → 晋升为 Canonical 公共字段 + - 否 → 暂不纳入，记录在适配清单中 +3. 设计：确定字段名（协议中立）、类型、在 Canonical 中的位置 +4. 更新：修改 Canonical Model 定义，所有现有 Adapter 的 Decoder/Encoder 同步更新 +5. 文档：更新 §10 字段映射参考表 +``` + +### 晋升示例 + +| 字段 | 原始位置 | 晋升原因 | +|------|---------|---------| +| `user_id` | OpenAI `user` / Anthropic `metadata.user_id` | 两协议均支持用户标识 | +| `output_format` | OpenAI `response_format` / Anthropic `output_format` | 两协议均支持控制输出格式 | +| `parallel_tool_use` | OpenAI `parallel_tool_calls` / Anthropic `disable_parallel_tool_use` | 两协议均支持并行工具调用控制 | +| `cache_control` | 仅 Anthropic | 不晋升，仅 Anthropic 使用 | +| `reasoning_content` | 仅 OpenAI | 不晋升（但 ThinkingBlock 已覆盖 thinking 语义） | + +### 降级规则 + +当公共字段的目标协议不支持时： +- 有语义等价物 → 自动映射（如 `parallel_tool_use` → `disable_parallel_tool_use`） +- 无等价物 → 丢弃，日志 warn（如 `output_format` → Anthropic 旧模型丢弃） +- 有替代方案 → 降级策略处理（如 `output_format` → 注入合成工具） + +--- + +## 附录 E：协议适配清单模板 + +适配新协议时，按以下清单逐项确认。所有项目确认后即可与引擎对接。 + +### E.1 协议基本信息 + +| 项目 | 说明 | +|------|------| +| 协议名称 | 用于 URL 前缀和 Adapter 注册的唯一标识（如 `"openai"`, `"anthropic"`） | +| 协议版本 | 当前适配的 API 版本（如 `"2023-06-01"`） | +| Base URL | API 服务地址 | +| 认证方式 | Header 名称和格式（如 `Authorization: Bearer` / `x-api-key`） | + +### E.2 接口识别 + +| 项目 | 说明 | +|------|------| +| URL 路径模式 | 列出所有接口的 URL 路径和对应的 InterfaceType | +| 接口能力矩阵 | 每种 InterfaceType 的支持状态（`supportsInterface`） | +| URL 映射表 | 每种 InterfaceType 的目标 URL 路径（`mapUrl`） | + +### E.3 请求头构建 + +| 项目 | 说明 | +|------|------| +| 认证头 | 如何从 `provider.api_key` 构建认证 Header | +| 必需 Header | 协议要求的固定 Header（如 Content-Type） | +| 可选 Header | 根据功能动态添加的 Header（如 anthropic-beta） | +| adapter_config 契约 | 定义本 Adapter 从 `provider.adapter_config` 读取的 key 列表和默认值 | + +### E.4 核心层 — Chat 请求编解码 + +#### Decoder（协议 → Canonical） + +| 项目 | 说明 | +|------|------| +| 系统消息 | 如何提取为 `canonical.system`（顶层字段 / messages 中 / 不支持） | +| 消息角色 | 协议角色与 Canonical 角色（system/user/assistant/tool）的映射 | +| 内容块 | 每种内容类型（text/tool_use/tool_result/thinking）的解码规则 | +| 工具定义 | 如何映射为 `canonical.tools`（字段名差异：input_schema vs parameters） | +| 工具选择 | tool_choice 各变体的映射规则 | +| 参数映射 | max_tokens/temperature/top_p/stop_sequences 等参数的映射 | +| 新增公共字段 | user_id/output_format/parallel_tool_use/thinking 的提取规则 | +| 协议特有字段 | 仅本协议使用的字段列表，以及处理方式（忽略/记录） | +| 协议约束 | 消息顺序要求、角色交替要求、必填字段等 | + +#### Encoder（Canonical → 协议） + +| 项目 | 说明 | +|------|------| +| 模型名称 | 使用 `provider.model_name` 覆盖 `canonical.model` | +| 系统消息注入 | 如何将 `canonical.system` 编码为协议格式 | +| 消息编码 | 各角色的编码规则（特别注意 role 映射、content 结构差异） | +| 角色约束处理 | 是否需要 enforceAlternation？具体策略？ | +| 工具编码 | tools/tool_choice 的编码规则 | +| 参数编码 | Canonical 参数到协议参数的映射 | +| 公共字段编码 | user_id/output_format/parallel_tool_use/thinking 的注入规则 | +| 降级处理 | 目标协议不支持的 Canonical 字段的降级策略 | + +### E.5 核心层 — Chat 响应编解码 + +| 项目 | 说明 | +|------|------| +| 响应结构 | 协议响应的顶层结构解析 | +| 内容块解码 | 各 content block 类型的解码规则 | +| 停止原因 | stop_reason / finish_reason 的映射表 | +| Token 用量 | usage 各字段的映射（注意命名差异：input_tokens vs prompt_tokens） | +| 推理内容 | reasoning_content / thinking block 的处理 | +| 协议特有内容 | 仅本协议返回的特有字段的处理 | + +### E.6 核心层 — 流式编解码 + +#### StreamDecoder（协议 SSE → Canonical 事件） + +| 项目 | 说明 | +|------|------| +| SSE 格式 | 协议的 SSE 事件格式（named events vs delta chunks） | +| 事件映射表 | 每种协议 SSE 事件 → CanonicalStreamEvent 的映射规则 | +| 状态机设计 | 需要跟踪的状态（当前 block index、open blocks、tool call 映射等） | +| UTF-8 安全 | 是否需要处理跨 chunk 的 UTF-8 截断 | +| 特殊情况 | 工具调用参数乱序、无限空白检测、延迟字段等 | + +#### StreamEncoder（Canonical 事件 → 协议 SSE） + +| 项目 | 说明 | +|------|------| +| 事件映射表 | 每个 CanonicalStreamEvent → 协议 SSE chunk 的映射规则 | +| 缓冲策略 | 哪些事件需要缓冲、何时输出 | +| SSE 格式 | event type / data 字段的编码方式 | +| 结束标记 | 如何输出流结束信号（如 `[DONE]`） | + +### E.7 扩展层接口 + +对每种支持的扩展层接口（/models、/embeddings、/files、/rerank、/count_tokens），确认： + +| 项目 | 说明 | +|------|------| +| 接口是否存在 | 该协议是否原生支持此接口 | +| URL 路径 | 接口的 URL 路径 | +| 请求格式 | 请求体的协议特有格式 → Canonical 格式的映射 | +| 响应格式 | 响应体的协议特有格式 ← Canonical 格式的映射 | +| 不支持时策略 | 透传 / 返回空响应 / 返回错误 | + +### E.8 错误编码 + +| 项目 | 说明 | +|------|------| +| 错误响应格式 | 协议的错误响应 JSON 结构 | +| encodeError | ConversionError → 协议错误格式的编码规则 | +| HTTP 状态码 | 协议常用的错误状态码映射 | + +### E.9 自检清单 + +- [ ] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 +- [ ] 所有 InterfaceType 的 `mapUrl` 映射已确定 +- [ ] Chat 请求的 Decoder 和 Encoder 已实现 +- [ ] Chat 响应的 Decoder 和 Encoder 已实现 +- [ ] 流式 StreamDecoder 和 StreamEncoder 已实现 +- [ ] `buildHeaders(provider)` 已实现 +- [ ] `encodeError` 已实现 +- [ ] 扩展层接口的编解码已实现（支持的接口） +- [ ] 角色映射和消息顺序约束已处理 +- [ ] 工具调用（tool_calls / tool_use / tool_result）的编解码已处理 +- [ ] stop_reason / finish_reason 映射表已确认 +- [ ] usage 字段映射已确认 +- [ ] 协议特有字段已识别并确定处理方式（忽略/降级） +- [ ] adapter_config 契约已文档化