大模型 API 核心规范——AI 应用开发必备前置知识大模型 API 核心规范——AI 应用开发必备前置知识一、为什么

大模型 API 核心规范——AI 应用开发必备前置知识

开发 AI 应用之前，必须搞清楚两件事：调哪个接口、入参出参长什么样。本文覆盖 OpenAI 规范（事实标准）和 Anthropic 规范（Claude），以及主流兼容厂商。

一、为什么要理解 API 规范

你写的代码          →    模型 API    →    输出
     ↑
必须按规范传参，否则报错

市面上模型虽多，接口规范只有两套：

OpenAI 规范：事实标准，大多数国产模型兼容
Anthropic 规范：Claude 独有，设计上有差异

理解这两套，市面上 90% 的模型都能接。

二、认证方式（两家都一样）

所有请求必须带 API Key：

# HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxx   # OpenAI 系
x-api-key: sk-ant-xxxxxxxxxxxx          # Anthropic

// SDK 初始化时传入，之后自动带上
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const claude = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })

铁律：API Key 只存环境变量，绝不写死在代码里，绝不提交到 git。

官方文档：

OpenAI 认证：platform.openai.com/docs/api-re…
Anthropic 认证：docs.anthropic.com/en/api/gett…

三、OpenAI 规范（事实标准）

3.1 接口总览

Base URL：https://api.openai.com/v1

/v1/chat/completions          POST  文字对话 + 图片理解（核心接口）
/v1/responses                 POST  新版 API，支持内置 web_search 工具
/v1/images/generations        POST  文生图
/v1/images/edits              POST  图片编辑
/v1/images/variations         POST  图片变体
/v1/audio/transcriptions      POST  语音→文字（ASR）
/v1/audio/translations        POST  语音→英文
/v1/audio/speech              POST  文字→语音（TTS）
/v1/realtime                  WS    实时语音对话（WebSocket）
/v1/embeddings                POST  文字→向量
/v1/moderations               POST  内容审核
/v1/fine_tuning/jobs          POST  微调任务管理
/v1/files                     POST  上传训练文件
/v1/models                    GET   查询可用模型列表
/v1/batches                   POST  批量请求（便宜 50%）
/v1/assistants                POST  创建 Assistant（Agent 框架）
/v1/threads                   POST  创建对话线程
/v1/threads/{id}/runs         POST  执行对话

官方完整参考：platform.openai.com/docs/api-re…

3.2 核心接口：文字对话

请求

POST /v1/chat/completions

{
  // ── 必填 ──────────────────────────────────────
  model:    'gpt-4o',
  messages: [
    { role: 'system',    content: '你是助手' },
    { role: 'user',      content: '你好' },
    { role: 'assistant', content: '你好！' },
    { role: 'user',      content: '帮我写标题' }
  ],

  // ── 控制输出 ──────────────────────────────────
  max_tokens:        1024,    // 输出 token 上限
  temperature:       0.7,     // 随机性 0-2，默认 1
  top_p:             1,       // 核采样，与 temperature 二选一调
  frequency_penalty: 0,       // 降低重复词，-2 到 2
  presence_penalty:  0,       // 鼓励新话题，-2 到 2
  stop:              ['\n'],  // 遇到这个字符串停止生成

  // ── 格式控制 ──────────────────────────────────
  response_format: { type: 'json_object' },  // 基础 JSON 模式（旧）
  // 推荐用 Structured Outputs，可指定具体 schema（新）：
  // response_format: {
  //   type: 'json_schema',
  //   json_schema: { name: 'result', schema: { type:'object', properties:{...} } }
  // }
  seed: 42,           // 固定随机种子，相同输入输出相近

  // ── 工具调用 ──────────────────────────────────
  tools: [{
    type: 'function',
    function: {
      name:        'get_weather',
      description: '获取天气',
      parameters: {              // JSON Schema
        type: 'object',
        properties: {
          city: { type: 'string' }
        },
        required: ['city']
      }
    }
  }],
  tool_choice: 'auto',          // auto / none / required / {type:'function',function:{name:'xxx'}}

  // ── 流式输出 ──────────────────────────────────
  stream: true,

  // ── 其他 ──────────────────────────────────────
  n:    1,          // 生成几个候选答案
  user: 'user_123'  // 传用户 ID，用于滥用检测
}

返回（非流式）

{
  id:      'chatcmpl-xxx',
  object:  'chat.completion',
  created: 1720000000,
  model:   'gpt-4o',

  choices: [{
    index:   0,
    message: {
      role:       'assistant',
      content:    '你好！有什么可以帮你？',
      tool_calls: [{                      // 如果模型要调工具
        id:       'call_001',
        type:     'function',
        function: { name: 'get_weather', arguments: '{"city":"北京"}' }
      }]
    },
    finish_reason: 'stop'                 // stop / tool_calls / length / content_filter
  }],

  usage: {
    prompt_tokens:     20,
    completion_tokens: 10,
    total_tokens:      30
  }
}

返回（流式 stream:true）

// 每行一个 SSE 事件
data: {"choices":[{"delta":{"content":"你"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"好"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"！"},"finish_reason":null}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

官方文档：platform.openai.com/docs/api-re…

3.3 生图接口

请求

POST /v1/images/generations

{
  model:   'dall-e-3',          // dall-e-3 / dall-e-2
  prompt:  '一只赛博朋克的猫',
  n:       1,                   // dall-e-3 只支持 1
  size:    '1024x1024',         // 1024x1024 / 1792x1024 / 1024x1792
  quality: 'hd',                // standard / hd（仅 dall-e-3）
  style:   'vivid',             // vivid / natural（仅 dall-e-3）

  response_format: 'url'        // url / b64_json
}

{
  created: 1720000000,
  data: [{
    url:            'https://oaidalleapiprodscus.blob.core.windows.net/...',
    revised_prompt: '模型优化后的 prompt...'   // dall-e-3 会返回这个
  }]
}

官方文档：platform.openai.com/docs/api-re…

3.3.5 图片理解 Vision（在 chat/completions 里）

图片理解不是单独接口，直接在 /v1/chat/completions 的 content 里传图片：

请求

POST /v1/chat/completions

{
  model: 'gpt-4o',
  messages: [{
    role: 'user',
    content: [
      {
        type: 'text',
        text: '这张图里有什么问题？'
      },
      {
        type: 'image_url',
        image_url: {
          url:    'https://example.com/image.jpg',  // 公开图片 URL
          detail: 'high'   // low（省 token）/ high（更精准）/ auto
        }
      }
      // 也可以用 base64
      // { type: 'image_url', image_url: { url: 'data:image/jpeg;base64,...' } }
    ]
  }]
}

返回：和普通文字对话完全一样，choices[0].message.content 是文字分析结果。

// 支持多图
content: [
  { type: 'text',      text: '对比这两张图的差异' },
  { type: 'image_url', image_url: { url: 'https://.../before.jpg' } },
  { type: 'image_url', image_url: { url: 'https://.../after.jpg' } }
]

token 消耗：图片也消耗 token，实际用量按图片分辨率动态计算（low 模式固定 85 token，high 模式按 512px 分块叠加，大图可达数千 token）。

官方文档：platform.openai.com/docs/guides…

3.4 语音转文字（ASR）

请求（multipart/form-data，不是 JSON）

POST /v1/audio/transcriptions

FormData:
  file:        audio.mp3        // 支持 mp3/mp4/wav/webm 等，最大 25MB
  model:       'whisper-1'
  language:    'zh'             // 可选，不填自动检测
  prompt:      '专有名词提示'   // 可选，帮助识别专有名词
  response_format: 'json'       // json / text / srt / vtt
  temperature: 0

{ "text": "识别出来的文字内容" }

官方文档：platform.openai.com/docs/api-re…

3.5 文字转语音（TTS）

请求

POST /v1/audio/speech

{
  model:           'tts-1',     // tts-1（快）/ tts-1-hd（高质量）
  input:           '要朗读的文字',
  voice:           'alloy',     // alloy / echo / fable / onyx / nova / shimmer
  response_format: 'mp3',       // mp3 / opus / aac / flac
  speed:           1.0          // 0.25 - 4.0
}

返回：直接是音频二进制流，不是 JSON

// 接收方式
const response = await fetch('/v1/audio/speech', { method: 'POST', body: ... })
const audioBuffer = await response.arrayBuffer()  // 直接转 buffer

官方文档：platform.openai.com/docs/api-re…

3.6 向量（Embedding）

请求

POST /v1/embeddings

{
  model:           'text-embedding-3-small',   // 推荐，性价比高
                   // 或 'text-embedding-3-large'（维度更高，更精准）
  input:           '要转成向量的文字',           // 字符串 或 字符串数组（批量）
  encoding_format: 'float',                    // float / base64
  dimensions:      1536                        // 可选，压缩维度（3-small 支持）
}

{
  object: 'list',
  data: [{
    object:    'embedding',
    index:     0,
    embedding: [0.12, -0.34, 0.89, ...]   // 1536 维浮点数组
  }],
  usage: { prompt_tokens: 5, total_tokens: 5 }
}

官方文档：platform.openai.com/docs/api-re…

3.7 批量请求（Batch API，省 50% 费用）

不需要实时返回的任务（数据处理、批量分析），用 Batch API 省一半钱：

// 1. 准备请求文件（JSONL 格式）
// requests.jsonl 每行一个请求：
{"custom_id":"req-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o","messages":[{"role":"user","content":"分析这段文字"}]}}
{"custom_id":"req-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o","messages":[{"role":"user","content":"翻译这段话"}]}}

// 2. 上传文件
const file = await openai.files.create({
  file:    fs.createReadStream('requests.jsonl'),
  purpose: 'batch'
})

// 3. 创建批量任务
const batch = await openai.batches.create({
  input_file_id:     file.id,
  endpoint:          '/v1/chat/completions',
  completion_window: '24h'    // 24小时内完成
})

// 4. 轮询状态 / 完成后取结果
const result = await openai.batches.retrieve(batch.id)

官方文档：platform.openai.com/docs/api-re…

3.9 Fine-tuning（微调）

用自己的数据训练，让模型输出符合特定风格或格式：

// 1. 准备训练数据（JSONL）
// training.jsonl 每行一个示例：
{"messages":[{"role":"system","content":"你是客服"},{"role":"user","content":"退款流程"},{"role":"assistant","content":"退款需3-5工作日..."}]}

// 2. 上传训练文件
const file = await openai.files.create({
  file:    fs.createReadStream('training.jsonl'),
  purpose: 'fine-tune'
})

// 3. 创建微调任务
const job = await openai.fineTuning.jobs.create({
  training_file: file.id,
  model:         'gpt-4o-mini',  // 基础模型
  hyperparameters: {
    n_epochs: 3                  // 训练轮数
  }
})

// 4. 查询进度
const status = await openai.fineTuning.jobs.retrieve(job.id)
// status.status: 'queued' / 'running' / 'succeeded' / 'failed'

// 5. 用微调后的模型（名字在 status.fine_tuned_model 里）
const response = await openai.chat.completions.create({
  model:    status.fine_tuned_model,  // 'ft:gpt-4o-mini:org:name:id'
  messages: [...]
})

什么时候用 Fine-tuning：

适合：改变输出风格/格式，有大量标注样本（>100条），高度专业化任务
不适合：注入最新知识（用 RAG），临时调整行为（用 prompt）

官方文档：platform.openai.com/docs/guides…

3.10 Assistants API（官方 Agent 框架）

OpenAI 封装的 Agent 框架，内置了对话历史管理、文件处理、工具调用：

核心概念：
  Assistant  → 配置好的 AI 角色（system prompt + 工具）
  Thread     → 一个对话会话（消息历史自动管理）
  Message    → Thread 里的一条消息
  Run        → 在 Thread 上执行 Assistant 的一次推理
  Step       → Run 的执行步骤（思考/工具调用/回复）

// 1. 创建 Assistant（一次性，可复用）
const assistant = await openai.beta.assistants.create({
  name:         '博客写作助手',
  instructions: '你是专业博客写作助手，风格简洁',
  model:        'gpt-4o',
  tools: [
    { type: 'code_interpreter' },  // 内置：执行代码
    { type: 'file_search' },       // 内置：检索上传的文件
    {                              // 自定义工具
      type: 'function',
      function: { name: 'get_blog_stats', description: '...', parameters: {...} }
    }
  ]
})

// 2. 创建对话 Thread（每个用户一个）
const thread = await openai.beta.threads.create()

// 3. 用户发消息
await openai.beta.threads.messages.create(thread.id, {
  role:    'user',
  content: '帮我分析这篇文章的数据'
})

// 4. 执行（Run）
const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
  assistant_id: assistant.id
})

// 5. 取结果
if (run.status === 'completed') {
  const messages = await openai.beta.threads.messages.list(thread.id)
  console.log(messages.data[0].content[0].text.value)
}

// 如果 run.status === 'requires_action'，说明需要执行自定义工具
if (run.status === 'requires_action') {
  const toolCalls = run.required_action.submit_tool_outputs.tool_calls
  const outputs = toolCalls.map(tc => ({
    tool_call_id: tc.id,
    output:       JSON.stringify(executeMyTool(tc.function.name, tc.function.arguments))
  }))
  await openai.beta.threads.runs.submitToolOutputs(thread.id, run.id, {
    tool_outputs: outputs
  })
}

Assistants API vs 自己实现 Tool Use：

Assistants API：
  ✓ 历史自动管理，不用自己维护 messages[]
  ✓ 内置 code_interpreter（沙箱执行代码）
  ✓ 内置 file_search（向量检索上传的文件）
  ✗ 不透明，调试困难
  ✗ 额外收费（file_search 按存储计费）

自己实现：
  ✓ 完全可控，便于调试
  ✓ 更灵活，可接任意模型
  ✗ 需要自己管理历史、工具循环

官方文档：platform.openai.com/docs/assist…

3.11 Realtime API（实时语音对话）

WebSocket 长连接，实现低延迟的实时语音交互：

// 不是 HTTP，是 WebSocket
const ws = new WebSocket(
  'wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview',
  {
    headers: {
      'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
      'OpenAI-Beta':   'realtime=v1'
    }
  }
)

// 配置会话
ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: {
      modalities:   ['text', 'audio'],
      instructions: '你是语音助手，回答简洁',
      voice:        'alloy',
      input_audio_format:  'pcm16',
      output_audio_format: 'pcm16',
      turn_detection: { type: 'server_vad' }  // 自动检测用户说话结束
    }
  }))
})

// 发送音频数据（PCM16 格式，base64 编码）
ws.send(JSON.stringify({
  type:  'input_audio_buffer.append',
  audio: base64AudioChunk
}))

// 接收事件
ws.on('message', (data) => {
  const event = JSON.parse(data)
  switch (event.type) {
    case 'response.audio.delta':
      // 收到音频片段，直接播放
      playAudio(event.delta)
      break
    case 'response.text.delta':
      // 收到文字片段（同步转录）
      console.log(event.delta)
      break
    case 'response.done':
      // 一轮对话结束
      break
  }
})

与 ASR+TTS 方案的区别：

传统方案：用户说话 → ASR转文字 → LLM处理 → TTS转语音 → 播放
延迟：    500ms   +  200ms   +  1000ms  +  300ms  = ~2s

Realtime API：语音直接输入输出，中间不转文字
延迟：~300ms
额外优势：能感知语气、停顿，打断更自然

官方文档：platform.openai.com/docs/guides…

3.12 内置工具（Built-in Tools）

不需要自己实现，声明即可用的官方工具。

Web Search

方式一：用专属模型（最简单）

// 直接换一个支持搜索的模型，不用声明工具
const response = await openai.chat.completions.create({
  model:    'gpt-4o-search-preview',   // 或 gpt-4o-mini-search-preview
  messages: [{ role: 'user', content: '今天有什么 AI 新闻？' }]
})
// 模型自动决定是否搜索，返回结果里带来源引用

方式二：Responses API（新版，可控制触发）

const response = await openai.responses.create({
  model: 'gpt-4o',
  tools: [{ type: 'web_search' }],     // 声明工具
  input: '最新的 Next.js 版本是什么？'
})

注意：Web Search 工具在 Responses API 中使用，Chat Completions API 需要用专属模型。

官方文档：platform.openai.com/docs/guides…

3.8 错误码

400 Bad Request     → 参数错误，检查入参
401 Unauthorized    → API Key 错误或失效
403 Forbidden       → 没有权限（如未开通某模型）
429 Too Many Requests → 触发限流，需要重试
500 Internal Server Error → OpenAI 服务器问题，重试
503 Service Unavailable   → 服务过载，重试

官方文档：platform.openai.com/docs/guides…

四、Anthropic 规范（Claude）

4.1 接口总览

Base URL：https://api.anthropic.com/v1

/v1/messages              POST  文字对话（核心接口）
/v1/messages/batches      POST  批量请求
/v1/models                GET   查询可用模型列表
/v1/files                 POST  上传文件

官方完整参考：docs.anthropic.com/en/api/mess…

4.2 核心接口：文字对话

请求

POST /v1/messages

// 必须带版本头
Headers:
  anthropic-version: 2023-06-01
  x-api-key: sk-ant-xxx

{
  // ── 必填 ──────────────────────────────────────
  model:      'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [
    { role: 'user',      content: '帮我写标题' },
    { role: 'assistant', content: '好的...' },
    { role: 'user',      content: '改短一点' }
  ],

  // ── 与 OpenAI 不同：system 是独立字段 ──────────
  system: '你是博客写作助手',
  // 或支持 cache（见下文）：
  system: [{
    type:          'text',
    text:          '你是博客写作助手...',
    cache_control: { type: 'ephemeral' }   // 开启 prompt cache
  }],

  // ── 控制输出 ──────────────────────────────────
  temperature: 0.7,     // 0-1（Claude 上限是 1，不是 2）
  top_p:       0.9,
  top_k:       40,
  stop_sequences: ['\n\n'],

  // ── 工具调用（字段名与 OpenAI 不同）────────────
  tools: [{
    name:        'get_weather',
    description: '获取天气',
    input_schema: {          // ← OpenAI 是 parameters，Claude 是 input_schema
      type: 'object',
      properties: {
        city: { type: 'string' }
      },
      required: ['city']
    }
  }],
  tool_choice: { type: 'auto' },   // auto / any / tool（指定具体工具）

  // ── 扩展思考 ──────────────────────────────────
  thinking: {
    type:         'enabled',
    budget_tokens: 8000      // 给模型多少 token 用来"想"
  },

  // ── 流式输出 ──────────────────────────────────
  stream: true
}

返回（非流式）

{
  id:           'msg_xxx',
  type:         'message',
  role:         'assistant',
  model:        'claude-sonnet-4-6',

  content: [
    { type: 'text', text: '你好！有什么可以帮你？' },
    // 如果有 thinking：
    { type: 'thinking', thinking: '用户在问候，我应该友好回应...' },
    // 如果要调工具：
    { type: 'tool_use', id: 'tu_001', name: 'get_weather', input: { city: '北京' } }
  ],

  stop_reason: 'end_turn',   // end_turn / tool_use / max_tokens / stop_sequence

  usage: {
    input_tokens:          20,
    output_tokens:         10,
    cache_creation_input_tokens: 500,   // 首次写入缓存的 token
    cache_read_input_tokens:     500    // 命中缓存的 token（收 1/10 价格）
  }
}

工具结果发回格式（与 OpenAI 不同）

// OpenAI 的工具结果
{ role: 'tool', tool_call_id: 'call_001', content: '结果' }

// Claude 的工具结果（放在 user 消息里）
{
  role: 'user',
  content: [{
    type:        'tool_result',
    tool_use_id: 'tu_001',          // 对应上面的 id
    content:     '{"temp": "25°C"}' // 工具执行结果
  }]
}

官方文档：docs.anthropic.com/en/api/mess…

4.3 Prompt Cache（Claude 独有优势）

重复的 system prompt 每次都重新计算很浪费，加 cache 标记后只计算一次：

system: [{
  type:          'text',
  text:          '一段很长的系统提示，比如几千字的业务背景...',
  cache_control: { type: 'ephemeral' }   // 5分钟内命中缓存
}]

// 价格对比：
// 正常 input token：$3 / 1M tokens
// cache 写入：      $3.75 / 1M tokens（贵一点）
// cache 命中：      $0.30 / 1M tokens（便宜 10 倍）

官方文档：docs.anthropic.com/en/docs/bui…

4.4 当前可用模型

claude-opus-4-6         最强，适合复杂推理
claude-sonnet-4-6       性价比最高，日常首选
claude-haiku-4-5        最快最便宜，简单任务

官方最新模型列表：docs.anthropic.com/en/docs/abo…

4.5 Extended Thinking（扩展思考）

让模型在回答前先"想清楚"，复杂推理任务效果显著提升：

const response = await client.messages.create({
  model:      'claude-sonnet-4-6',
  max_tokens: 16000,
  thinking: {
    type:          'enabled',
    budget_tokens: 8000    // 给模型最多用多少 token 思考
  },
  messages: [{ role: 'user', content: '分析这段代码的性能瓶颈' }]
})

// content 里同时有 thinking 块和 text 块
response.content.forEach(block => {
  if (block.type === 'thinking') {
    console.log('思考过程：', block.thinking)  // 模型内心独白
  }
  if (block.type === 'text') {
    console.log('最终回答：', block.text)
  }
})

注意：开启 thinking 时 temperature 必须为 1，max_tokens 要足够大，thinking 块也计入输出 token 收费。适合复杂推理，简单问答不要开。

官方文档：docs.anthropic.com/en/docs/bui…

4.6 Files API（上传文件）

上传文件后用 file_id 引用，无需每次传完整内容：

// 1. 上传
const file = await client.beta.files.upload({
  file: fs.createReadStream('document.pdf')
})

// 2. 引用
const response = await client.messages.create({
  model:      'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: '总结这份文档' },
      {
        type:   'document',
        source: { type: 'file', file_id: file.id }
      }
    ]
  }]
})

// 3. 清理
await client.beta.files.delete(file.id)

支持格式：PDF、TXT、CSV、图片（JPEG/PNG/GIF/WEBP）

官方文档：docs.anthropic.com/en/docs/bui…

4.7 Vision（图片理解）

和 OpenAI 类似，在 messages content 里传图片：

{
  role: 'user',
  content: [
    { type: 'text', text: '这张截图有什么问题？' },
    {
      type:   'image',
      source: {
        type:       'base64',
        media_type: 'image/jpeg',
        data:       base64ImageData
      }
      // 或直接传 URL：
      // source: { type: 'url', url: 'https://...' }
    }
  ]
}

官方文档：docs.anthropic.com/en/docs/bui…

4.8 内置工具（Built-in Tools）

Anthropic 提供两类内置工具，无需自己实现执行逻辑：

服务端工具（Anthropic 的服务器执行）：
  web_search   → 联网搜索
  web_fetch    → 抓取指定 URL 内容

客户端工具（你的机器执行，模型发指令，你来运行）：
  computer_use → 控制屏幕/鼠标/键盘
  bash         → 执行 shell 命令
  text_editor  → 查看和编辑文件

Web Search（联网搜索）

const response = await client.messages.create({
  model:      'claude-sonnet-4-6',
  max_tokens: 1024,
  tools: [{
    type: 'web_search_20260209',  // 最新版本
    name: 'web_search',
    max_uses:        5,           // 最多搜几次
    allowed_domains: ['github.com', 'docs.anthropic.com'],  // 可选白名单
    blocked_domains: ['pinterest.com'],                      // 可选黑名单
  }],
  messages: [{ role: 'user', content: '最新的 Claude 模型有哪些？' }]
})
// 模型自动调用搜索，结果注入上下文，然后回答
// 返回结构和普通消息一样，content 里含 text 块

Web Fetch（抓取网页）

tools: [{
  type: 'web_fetch_20250124',
  name: 'web_fetch',
}]
// 模型会在需要时调用，抓取指定 URL 的内容
// 用户也可以直接让它抓：
// "帮我总结一下 https://example.com/article 这篇文章"

Computer Use（控制电脑）

// 模型发出操作指令，你的代码负责执行
tools: [{
  type: 'computer_20251124',
  name: 'computer',
  display_width_px:  1280,
  display_height_px: 800,
}]

// 模型返回的操作指令示例：
// { type: 'tool_use', name: 'computer', input: { action: 'screenshot' } }
// { type: 'tool_use', name: 'computer', input: { action: 'left_click', coordinate: [100, 200] } }
// { type: 'tool_use', name: 'computer', input: { action: 'type', text: 'hello' } }

// 你执行截图/点击后，把结果（截图 base64）发回模型

服务端 vs 客户端的核心区别：

web_search / web_fetch → 模型直接调，不经过你的代码，结果自动注入
computer_use / bash     → 模型发指令，你写代码执行，结果手动发回

官方文档：

Web Search：docs.anthropic.com/en/docs/bui…
Computer Use：docs.anthropic.com/en/docs/bui…

五、两套规范核心差异对比

                    OpenAI 规范              Anthropic 规范
────────────────────────────────────────────────────────────
system 位置         messages[0]              独立参数 system
tool 字段名         parameters               input_schema
tool 结果 role      role: 'tool'             role: 'user' 里嵌套
返回内容路径        choices[0].message       content[0].text
finish_reason       stop / tool_calls        end_turn / tool_use
temperature 上限    2                        1
流式格式            choices[0].delta         content_block_delta
批量 API            /v1/batches              /v1/messages/batches
图片理解            content 里传 image_url   content 里传 image
生图/语音接口       有                       无（纯文字+视觉模型）
Prompt Cache        无                       有（省 90% 重复费用）
Extended Thinking   无                       有
Files API           有（主要用于微调）        有（用于对话引用）
Agent 框架          Assistants API           自行实现 Tool Use 循环
实时语音            Realtime API（WebSocket）无

六、兼容 OpenAI 规范的主流厂商

只需换 baseURL 和 model 名，代码不动：

// DeepSeek
const client = new OpenAI({
  baseURL: 'https://api.deepseek.com/v1',
  apiKey:  process.env.DEEPSEEK_API_KEY
})
// 文档：https://platform.deepseek.com/api-docs

// 月之暗面 Kimi
const client = new OpenAI({
  baseURL: 'https://api.moonshot.cn/v1',
  apiKey:  process.env.MOONSHOT_API_KEY
})
// 文档：https://platform.moonshot.cn/docs

// 阿里千问
const client = new OpenAI({
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey:  process.env.DASHSCOPE_API_KEY
})
// 文档：https://help.aliyun.com/zh/model-studio/developer-reference

// 字节豆包
const client = new OpenAI({
  baseURL: 'https://ark.cn-beijing.volces.com/api/v3',
  apiKey:  process.env.ARK_API_KEY
})
// 文档：https://www.volcengine.com/docs/82379

// 本地 Ollama（完全免费）
const client = new OpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey:  'ollama'
})
// 文档：https://ollama.com/blog/openai-compatibility

七、用统一 SDK 抹平差异

项目里同时用多个模型时，推荐用 Vercel AI SDK：

import { generateText, streamText } from 'ai'
import { openai }     from '@ai-sdk/openai'
import { anthropic }  from '@ai-sdk/anthropic'

// 切换模型只改一行
const model = anthropic('claude-sonnet-4-6')
// const model = openai('gpt-4o')

const { text } = await generateText({
  model,
  system:   '你是助手',
  prompt:   '你好',
})

// 流式输出
const { textStream } = streamText({ model, prompt: '写一篇文章' })
for await (const chunk of textStream) {
  process.stdout.write(chunk)
}

官方文档：sdk.vercel.ai/docs

八、限流和重试

所有厂商都有限流，生产环境必须处理：

async function callWithRetry(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error: any) {
      if (error.status === 429) {
        // 限流：指数退避重试
        const wait = Math.pow(2, i) * 1000   // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, wait))
        continue
      }
      throw error  // 其他错误直接抛出
    }
  }
}

// 使用
const response = await callWithRetry(() =>
  client.chat.completions.create({ ... })
)

九、快速参考卡

用途               接口                          SDK 方法
──────────────────────────────────────────────────────────────────
文字对话           /v1/chat/completions          client.chat.completions.create()
图片理解           /v1/chat/completions          同上，content 里加 image_url
生图               /v1/images/generations        client.images.generate()
语音→文字          /v1/audio/transcriptions      client.audio.transcriptions.create()
文字→语音          /v1/audio/speech              client.audio.speech.create()
实时语音           /v1/realtime                  WebSocket 连接
向量               /v1/embeddings                client.embeddings.create()
内容审核           /v1/moderations               client.moderations.create()
批量请求           /v1/batches                   client.batches.create()
微调               /v1/fine_tuning/jobs          client.fineTuning.jobs.create()
Agent（官方）      /v1/assistants + /threads     client.beta.assistants.create()
查模型列表         /v1/models                    client.models.list()

十、核心文档索引

内容	链接
OpenAI API 完整文档	platform.openai.com/docs/api-re…
OpenAI 模型列表	platform.openai.com/docs/models
OpenAI Vision	platform.openai.com/docs/guides…
OpenAI 错误码	platform.openai.com/docs/guides…
OpenAI 限流说明	platform.openai.com/docs/guides…
OpenAI Fine-tuning	platform.openai.com/docs/guides…
OpenAI Assistants API	platform.openai.com/docs/assist…
OpenAI Realtime API	platform.openai.com/docs/guides…
Anthropic API 完整文档	docs.anthropic.com/en/api/mess…
Anthropic 模型列表	docs.anthropic.com/en/docs/abo…
Anthropic Prompt Cache	docs.anthropic.com/en/docs/bui…
Anthropic Tool Use	docs.anthropic.com/en/docs/bui…
Anthropic Extended Thinking	docs.anthropic.com/en/docs/bui…
Anthropic Files API	docs.anthropic.com/en/docs/bui…
Anthropic Vision	docs.anthropic.com/en/docs/bui…
OpenAI Web Search	platform.openai.com/docs/guides…
Anthropic Web Search	docs.anthropic.com/en/docs/bui…
Anthropic Computer Use	docs.anthropic.com/en/docs/bui…
DeepSeek API	platform.deepseek.com/api-docs
阿里千问 API	help.aliyun.com/zh/model-st…