POST https://api.openai.com/v1/chat/completions

Content-Type: application/json
Authorization: Bearer sk-...
OpenAI-Organization: org-...   ← 可选
OpenAI-Project: proj_...        ← 可选

POST https://api.anthropic.com/v1/messages

Content-Type: application/json
x-api-key: sk-ant-api03-...
anthropic-version: 2023-06-01  ← 必填
anthropic-beta: ...             ← Beta 功能时使用

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "You are helpful.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",        ← system 在 messages 中
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hi, how are you?"
    }
  ]
}

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,           ← 必填
  "system": "You are a helpful assistant.",  ← 顶层字段
  "messages": [
    {
      "role": "user",
      "content": "Hi, how are you?"
    }
  ]
}

// OpenAI 支持在 messages 中放置多条 system 消息
"messages": [
  {"role": "system",
   "content": "You are a translator."},
  {"role": "system",
   "content": "Always respond in JSON."},
  {"role": "user",
   "content": "Translate: Hello"}
]

// 也可以在对话中间插入 system 消息

// system 支持 block 数组格式（可附加 cache_control）
"system": [
  {
    "type": "text",
    "text": "You are a translator.",
    "cache_control": {"type": "ephemeral"}
  },
  {
    "type": "text",
    "text": "Always respond in JSON."
  }
]

// 简写：content 为字符串
{"role": "user", "content": "Hello"}

// 完整写法：content 为数组（多模态时必须用此格式）
{"role": "user",
 "content": [
   {"type": "text", "text": "Hello"},
   {"type": "image_url", "image_url": {"url": "..."}}
 ]}

// 简写：content 为字符串
{"role": "user", "content": "Hello"}

// 完整写法：content 为 block 数组（多模态时必须用此格式）
{"role": "user",
 "content": [
   {"type": "text", "text": "Hello"},
   {"type": "image", "source": {"type": "url", "url": "..."}}
 ]}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-2024-08-06",
  "choices": [{                  ← choices 数组包裹
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "I'm doing well!"  ← 纯字符串
    },
    "finish_reason": "stop"        ← 结束原因在 choice 内
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [{                  ← content block 数组
    "type": "text",
    "text": "I'm doing well!"  ← block 中的 text 字段
  }],
  "stop_reason": "end_turn",      ← 结束原因在顶层
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

// 文本
response.choices[0].message.content  → 字符串

// 结束原因
response.choices[0].finish_reason

// Token 用量
response.usage.prompt_tokens
response.usage.completion_tokens
response.usage.total_tokens

// 文本
response.content[0].text  → 字符串

// 结束原因
response.stop_reason

// Token 用量
response.usage.input_tokens
response.usage.output_tokens
// 无 total，需自行相加

"usage": {
  "prompt_tokens": 2048,        ← 含 cached_tokens
  "completion_tokens": 512,     ← 含 reasoning_tokens
  "total_tokens": 2560,

  "prompt_tokens_details": {
    "cached_tokens": 1024,      ← 自动命中缓存
    "audio_tokens": 0            ← 音频输入(GPT-4o-audio)
  },

  "completion_tokens_details": {
    "reasoning_tokens": 256,    ← o1/o3/o4 思考
    "audio_tokens": 0,           ← 音频输出
    "accepted_prediction_tokens": 0,
    "rejected_prediction_tokens": 0
  }
}

// 计费示例（GPT-4o，价格仅示意）：
// 普通输入: (2048 - 1024) × $2.50/M = ...
// 缓存输入: 1024 × $1.25/M = ...
// 输出: 512 × $10.00/M = ...
// (reasoning_tokens 已在 completion_tokens 中)

"usage": {
  "input_tokens": 512,             ← 未命中也未写缓存
  "cache_creation_input_tokens": 1024,
  "cache_read_input_tokens": 2048,

  "cache_creation": {              ← 缓存写入按 TTL 拆分
    "ephemeral_5m_input_tokens": 512,
    "ephemeral_1h_input_tokens": 512
  },

  "output_tokens": 768,            ← thinking + 正文
  "server_tool_use": {              ← 服务端工具计量
    "web_search_requests": 2
  },
  "service_tier": "standard"      ← standard/priority/batch
}

// 计费示例（Claude Sonnet 4，价格仅示意）：
// 普通输入: 512 × $3.00/M = ...
// 缓存写入(5m): 512 × $3.75/M (1.25×) = ...
// 缓存写入(1h): 512 × $6.00/M (2.00×) = ...
// 缓存读取: 2048 × $0.30/M (0.10×) = ...
// 输出: 768 × $15.00/M = ...

// 思考 token 是 completion 的子集，不可读
"usage": {
  "prompt_tokens": 100,
  "completion_tokens": 1500,
  "completion_tokens_details": {
    "reasoning_tokens": 1200  ← 隐式思考
  }
}

// 关键点：
// 1. reasoning_tokens 已包含在 completion_tokens 中
// 2. 计费时按 output 价计算 (整个 completion)
// 3. 思考内容对用户不可见（仅返回 summary）
// 4. max_completion_tokens 需要预留思考预算
//    （而非旧的 max_tokens，o-系列已弃用）
// 5. 通过 reasoning_effort: "low/medium/high"
//    控制思考深度

// 思考 token 计入 output_tokens，但内容可见
"usage": {
  "input_tokens": 100,
  "output_tokens": 1500  ← thinking + 正文
}

"content": [
  {"type":"thinking","thinking":"Let me ...",
   "signature":"abc..."},  ← 思考块（可见）
  {"type":"text","text":"答案是 42"}
]

// 关键点：
// 1. thinking 文本按 output 价计费
// 2. 通过 thinking.budget_tokens 控制上限
// 3. budget_tokens 必须 < max_tokens
// 4. 多轮回传时需要带回 signature 才会被采信
// 5. 工具调用循环中必须回传 thinking block

// 请求体必须加 stream_options
{
  "model": "gpt-4o",
  "messages": [...],
  "stream": true,
  "stream_options": {"include_usage": true}
}

// 中间事件 usage 字段为 null
data: {"choices":[{"delta":{...}}],
       "usage": null}

// 倒数第二个 chunk（choices 为空）携带 usage
data: {"choices": [],
       "usage": {
         "prompt_tokens": 12,
         "completion_tokens": 8,
         "total_tokens": 20
       }}

data: [DONE]

// 不加 include_usage 时整个流没有 usage 字段

// 无需任何额外配置

// 首个事件 message_start 含 input_tokens
event: message_start
data: {"type":"message_start","message":{
  ...,
  "usage":{
    "input_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 1  ← 仅占位
  }}}

// 末尾事件 message_delta 含 output_tokens
event: message_delta
data: {"type":"message_delta",
  "delta":{"stop_reason":"end_turn"},
  "usage":{"output_tokens": 8}}

// 需要合并 message_start.usage + message_delta.usage
// 才能拿到完整的 usage 对象

// 场景：o3 模型 + 长 system + 多轮对话
"usage": {
  "prompt_tokens": 5200,        ← system + 历史
  "completion_tokens": 800,
  "total_tokens": 6000,
  "prompt_tokens_details": {
    "cached_tokens": 4800      ← 92% 命中
  },
  "completion_tokens_details": {
    "reasoning_tokens": 600    ← 75% 用于推理
  }
}

// 计算（假设 $2/M 输入, $1/M 缓存, $8/M 输出）：
// 非缓存输入: (5200 - 4800) × $2/M = $0.0008
// 缓存输入:   4800 × $1/M = $0.0048
// 输出(含推理): 800 × $8/M = $0.0064
// 合计: ≈ $0.012

// 场景：Sonnet 4 + cache + thinking + 工具调用
"usage": {
  "input_tokens": 120,            ← 仅本轮新增
  "cache_creation_input_tokens": 800,
  "cache_read_input_tokens": 4280,  ← 83% 复用
  "cache_creation": {
    "ephemeral_5m_input_tokens": 800
  },
  "output_tokens": 900,            ← thinking + tool_use + text
  "server_tool_use": {"web_search_requests": 1},
  "service_tier": "standard"
}

// 计算（假设 $3/M 输入, $15/M 输出）：
// 普通输入: 120 × $3/M = $0.00036
// 缓存写入: 800 × $3.75/M (1.25×) = $0.003
// 缓存读取: 4280 × $0.30/M (0.10×) = $0.00128
// 输出: 900 × $15/M = $0.0135
// Web 搜索: 1 × $10/1000 = $0.01
// 合计: ≈ $0.028
// 实际处理输入 = 120 + 800 + 4280 = 5200 tokens

// 请求体加 user 字段，便于在 Dashboard / 风控里聚合
{
  "model": "gpt-4o",
  "messages": [...],
  "user": "user_8a3f..."     ← 字符串，自由格式
}

// 响应中没有 user 回显，但可在用量报告中按 user 切片
// 项目 / 组织维度通过 OpenAI-Project / OpenAI-Organization
// 请求头自动归类

// 多轮 token 聚合 = 每次响应的 total_tokens 累加
// （已含 cached_tokens，不会重复计费）

// 请求体加 metadata.user_id 用于滥用检测和报表
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [...],
  "metadata": {
    "user_id": "user_8a3f..."  ← 建议哈希化
  }
}

// 多轮 token 聚合需要分别累加：
//   total_input = Σ (input + cache_creation + cache_read)
//   total_output = Σ output_tokens
// 否则会漏掉缓存读写的两类输入 token

// 注意：metadata.user_id 不会出现在响应中，
// 仅用于服务端聚合和滥用检测

{
  "error": {
    "message": "Incorrect API key provided: sk-...xxxx.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

// 错误类型：invalid_request_error, authentication_error,
// permission_error, rate_limit_error, server_error

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

// 错误类型：invalid_request_error, authentication_error,
// permission_error, not_found_error, rate_limit_error,
// api_error, overloaded_error

"tools": [{
  "type": "function",       ← 额外包裹层
  "function": {
    "name": "get_weather",
    "description": "Get weather info",
    "parameters": {         ← "parameters"
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name"
        }
      },
      "required": ["location"]
    },
    "strict": false          ← 可选：强制结构化输出
  }
}]

"tools": [{
  "name": "get_weather",       ← 直接平铺
  "description": "Get weather info",
  "input_schema": {           ← "input_schema"
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  }
}]

// 模型自行决定（默认）
"tool_choice": "auto"

// 禁止使用工具
"tool_choice": "none"

// 强制使用工具（不限定哪个）
"tool_choice": "required"

// 指定使用某个工具
"tool_choice": {
  "type": "function",
  "function": {"name": "get_weather"}
}

// 控制并行工具调用
"parallel_tool_calls": false

// 模型自行决定（默认）
"tool_choice": {"type": "auto"}

// 无 "none" — 不传 tools 即可

// 强制使用工具（不限定哪个）
"tool_choice": {"type": "any"}

// 指定使用某个工具
"tool_choice": {
  "type": "tool",
  "name": "get_weather"
}

// 控制并行工具调用（嵌套在 tool_choice 中）
"tool_choice": {
  "type": "auto",
  "disable_parallel_tool_use": true
}

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,         ← 有工具调用时 content 为 null
      "tool_calls": [{        ← 独立的 tool_calls 字段
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\":\"San Francisco\"}"
        }               ↑ arguments 是 JSON 字符串
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

{
  "role": "assistant",
  "content": [
    {
      "type": "text",           ← 可以有文本说明
      "text": "Let me check the weather."
    },
    {
      "type": "tool_use",       ← 工具调用也在 content 数组中
      "id": "toolu_abc123",
      "name": "get_weather",
      "input": {"location": "San Francisco"}
    }                    ↑ input 是已解析的 JSON 对象
  ],
  "stop_reason": "tool_use"
}

"tool_calls": [
  {
    "id": "call_1",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"SF\"}"
    }
  },
  {
    "id": "call_2",
    "type": "function",
    "function": {
      "name": "get_time",
      "arguments": "{\"timezone\":\"PST\"}"
    }
  }
]

"content": [
  {"type": "text",
   "text": "I'll check both for you."},
  {
    "type": "tool_use",
    "id": "toolu_1",
    "name": "get_weather",
    "input": {"location": "SF"}
  },
  {
    "type": "tool_use",
    "id": "toolu_2",
    "name": "get_time",
    "input": {"timezone": "PST"}
  }
]

// 每个 tool_call 对应一条 tool 消息
{
  "role": "tool",
  "tool_call_id": "call_1",
  "content": "24°C, sunny"
},
{
  "role": "tool",
  "tool_call_id": "call_2",
  "content": "2:30 PM PST"
}

// 所有结果放在一条 user 消息的 content 数组中
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_1",
      "content": "24°C, sunny"
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_2",
      "content": "2:30 PM PST"
    }
  ]
}

// 首个 chunk — 携带 role
data: {"id":"chatcmpl-...","choices":[{
  "delta":{"role":"assistant","content":""},
  "index":0}]}

// 文本增量（逐 token）
data: {"choices":[{"delta":{
  "content":"I'm"},"index":0}]}

data: {"choices":[{"delta":{
  "content":" doing"},"index":0}]}

data: {"choices":[{"delta":{
  "content":" well!"},"index":0}]}

// 结束标记
data: {"choices":[{"delta":{},
  "finish_reason":"stop"}]}

data: [DONE]

// 消息开始（含 message 元信息和 usage）
event: message_start
data: {"type":"message_start","message":{
  "id":"msg_...","role":"assistant",
  "usage":{"input_tokens":12,...}}}

// 内容块开始（声明类型 → text）
event: content_block_start
data: {"type":"content_block_start",
  "index":0,
  "content_block":{"type":"text","text":""}}

// 文本增量（逐 token）
event: content_block_delta
data: {"type":"content_block_delta","index":0,
  "delta":{"type":"text_delta",
    "text":"I'm doing well!"}}

// 内容块结束
event: content_block_stop
data: {"type":"content_block_stop","index":0}

// 消息增量（含 stop_reason 和 output usage）
event: message_delta
data: {"type":"message_delta",
  "delta":{"stop_reason":"end_turn"},
  "usage":{"output_tokens":8}}

// 消息结束
event: message_stop
data: {"type":"message_stop"}

// 工具调用开始（首个 chunk 含完整元信息）
data: {"choices":[{"delta":{
  "tool_calls":[{"index":0,
    "id":"call_abc",
    "type":"function",
    "function":{"name":"get_weather",
      "arguments":""}}]}}]}

// arguments 分段传输（JSON 字符串片段）
data: {"choices":[{"delta":{
  "tool_calls":[{"index":0,
    "function":{"arguments":"{\"lo"}}]}}]}

data: {"choices":[{"delta":{
  "tool_calls":[{"index":0,
    "function":{"arguments":"cation\":\"SF\"}"}}]}}]}

// 结束
data: {"choices":[{"delta":{},
  "finish_reason":"tool_calls"}]}
data: [DONE]

// 工具调用块开始（声明 block 类型 + 元信息）
event: content_block_start
data: {"type":"content_block_start",
  "index":1,
  "content_block":{"type":"tool_use",
    "id":"toolu_abc",
    "name":"get_weather",
    "input":{}}}

// input 分段传输（JSON 片段）
event: content_block_delta
data: {"type":"content_block_delta",
  "index":1,
  "delta":{"type":"input_json_delta",
    "partial_json":"{\"location"}}

event: content_block_delta
data: {"delta":{"type":"input_json_delta",
    "partial_json":"\":\"SF\"}"}}

// 工具调用块结束
event: content_block_stop
data: {"type":"content_block_stop","index":1}

// 思考默认内嵌在 content 中
// 通过 reasoning_split 分离思考和回答
{
  "model": "gpt-4o",
  "messages": [...],
  "reasoning_split": true  ← 可选：分离思考内容
}

// 不使用 reasoning_split 时，思考过程
// 以 <think>...</think> 标签嵌入 content 字符串

// 通过 thinking 参数显式启用
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000   ← 思考 token 预算
  },
  "messages": [...]
}

// budget_tokens 控制模型可用于思考的最大 token 数
// 必须小于 max_tokens

// 默认：思考嵌入 content 字符串
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "<think>\nLet me analyze this step by step.\n1. First...\n2. Then...\n</think>\n\nThe answer is 42."
    }
  }]
}

// 使用 reasoning_split=true 时：
{
  "choices": [{
    "message": {
      "content": "The answer is 42.",
      "reasoning_details": [{
        "type": "reasoning.text",
        "text": "Let me analyze this step by step.\n1. First...\n2. Then..."
      }]
    }
  }]
}

// 思考作为独立的 content block
{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step.\n1. First...\n2. Then..."
    },
    {
      "type": "text",
      "text": "The answer is 42."
    }
  ]
}

// 多步推理可能产生多个 thinking + text 交错：
// [thinking, text, thinking, tool_use, ...]

// 默认：思考和回答混在 delta.content 中
data: {"choices":[{"delta":{
  "content":"<think>\nLet me"}}]}
data: {"choices":[{"delta":{
  "content":" analyze..."}}]}
data: {"choices":[{"delta":{
  "content":"</think>\n\nThe answer"}}]}

// 使用 reasoning_split=true 时：
// 思考增量通过 delta.reasoning_details 传输
// 回答增量通过 delta.content 传输
data: {"choices":[{"delta":{
  "reasoning_details":[{
    "type":"reasoning.text",
    "text":"Let me analyze..."}]}}]}

// thinking block 开始 — 声明类型
event: content_block_start
data: {"index":0,"content_block":{
  "type":"thinking","thinking":""}}

// thinking 增量（thinking_delta 类型）
event: content_block_delta
data: {"index":0,"delta":{
  "type":"thinking_delta",
  "thinking":"Let me analyze..."}}

event: content_block_stop
data: {"index":0}

// text block 开始 — 声明类型
event: content_block_start
data: {"index":1,"content_block":{
  "type":"text","text":""}}

// text 增量（text_delta 类型）
event: content_block_delta
data: {"index":1,"delta":{
  "type":"text_delta",
  "text":"The answer is 42."}}

// 默认格式：原样回传包含 <think> 的 content
{"role": "assistant",
 "content": "<think>...</think>\n\nThe answer is 42."}

// reasoning_split 格式：回传 reasoning_details
{"role": "assistant",
 "content": "The answer is 42.",
 "reasoning_details": [{
   "type": "reasoning.text",
   "text": "Let me analyze..."
 }]}

// 必须完整回传 content 数组（含 signature）
{"role": "assistant",
 "content": [
   {
     "type": "thinking",
     "thinking": "Let me analyze...",
     "signature": "WyIxNjk3..."  ← 必须保留
   },
   {
     "type": "text",
     "text": "The answer is 42."
   }
 ]}

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What's in this image?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "auto"  ← "low" / "high" / "auto"
      }
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What's in this image?"
    },
    {
      "type": "image",
      "source": {
        "type": "url",
        "url": "https://example.com/photo.jpg"
      }
    }
  ]
}

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,iVBORw0KGgo..."
  }
}

// base64 数据嵌入 data URI scheme 中
// 格式：data:{media_type};base64,{data}
// media_type 从 URI 中推断

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/png",
    "data": "iVBORw0KGgo..."
  }
}

// media_type 作为独立字段显式声明
// data 为纯 base64 字符串（不含 data URI 前缀）

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system",
     "content": "You are a helpful assistant."},
    {"role": "user",
     "content": "What's 2+2?"},
    {"role": "assistant",
     "content": "2 + 2 = 4."},
    {"role": "user",
     "content": "Multiply that by 3"}
  ]
}

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user",
     "content": "What's 2+2?"},
    {"role": "assistant",
     "content": [{"type":"text",
       "text":"2 + 2 = 4."}]},
    {"role": "user",
     "content": "Multiply that by 3"}
  ]
}

"messages": [
  // ① 用户提问
  {"role": "user",
   "content": "SF weather?"},

  // ② 模型决定调用工具（原样回传）
  {"role": "assistant",
   "content": null,
   "tool_calls": [{
     "id": "call_1",
     "type": "function",
     "function": {
       "name": "get_weather",
       "arguments": "{\"location\":\"SF\"}"
     }
   }]},

  // ③ 工具执行结果
  {"role": "tool",
   "tool_call_id": "call_1",
   "content": "24°C, sunny"},

  // ④ 用户继续对话
  {"role": "user",
   "content": "Will it rain tomorrow?"}
]

"messages": [
  // ① 用户提问
  {"role": "user",
   "content": "SF weather?"},

  // ② 模型决定调用工具（完整 content 回传）
  {"role": "assistant",
   "content": [
     {"type": "text",
      "text": "Let me check."},
     {"type": "tool_use",
      "id": "toolu_1",
      "name": "get_weather",
      "input": {"location": "SF"}}
   ]},

  // ③ 工具结果 + 用户续问（合并为一条 user 消息）
  {"role": "user",
   "content": [
     {"type": "tool_result",
      "tool_use_id": "toolu_1",
      "content": "24°C, sunny"},
     {"type": "text",
      "text": "Will it rain tomorrow?"}
   ]}
]