Agent 工具使用笔记——API 接入

这篇记一下大模型 API 接入。目标不复杂：知道一次请求由哪些东西组成，然后能把 DeepSeek、OpenRouter 这类服务填到各种 AI 软件、编辑器插件、agent 工具或自己的脚本里。

主要参考 DeepSeek 和 OpenRouter 官方文档。示例只保留最小字段，高级参数先不展开。

调用原理

最小调用一般绕不开这几项：

API format: OpenAI-compatible / Anthropic-compatible / ...
Base URL: https://api.example.com
API key: sk-...
Model: provider/model-name

真正发 HTTP 请求时，还会多出这些东西：

Endpoint: /chat/completions
Headers: Authorization + Content-Type
Body: model + messages

最常见的是 OpenAI-compatible Chat Completions 格式：

POST <base_url>/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体最核心就是 model 和 messages：

{
  "model": "model-name",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

所以第三方软件里所谓“配置 API”，大部分时候就是填这几个字段：

Provider / API format
Base URL
API key
Model name

Base URL

Base URL 是最容易填错的地方。不同服务的写法不完全一样：

DeepSeek OpenAI-compatible: https://api.deepseek.com
DeepSeek Anthropic-compatible: https://api.deepseek.com/anthropic
OpenRouter OpenAI-compatible: https://openrouter.ai/api/v1

我一般这样判断：

• 如果软件要求填写完整 OpenAI-compatible base URL，OpenRouter 通常填 https://openrouter.ai/api/v1。
• DeepSeek 官方 OpenAI SDK 示例使用 https://api.deepseek.com，请求路径是 /chat/completions。
• 有些软件会自动追加 /v1，有些不会。遇到 404，优先检查 base URL 是否多写或少写了路径。
• Endpoint 不是 Base URL。https://openrouter.ai/api/v1 是 base URL，/chat/completions 是 endpoint。

API key

API key 就是鉴权凭据。OpenAI-compatible 服务通常使用：

Authorization: Bearer <API_KEY>

本地临时测试可以放环境变量：

$env:DEEPSEEK_API_KEY = "sk-..."
$env:OPENROUTER_API_KEY = "sk-or-..."

不要把 API key 写到这些地方：

• AGENTS.md
• CLAUDE.md
• SKILL.md
• .env.example
• 博客文章
• 截图
• 项目共享配置

DeepSeek

DeepSeek 官方文档里同时给了 OpenAI-compatible 和 Anthropic-compatible 两种格式。常用配置是：

OpenAI-compatible base URL: https://api.deepseek.com
Anthropic-compatible base URL: https://api.deepseek.com/anthropic
API key: DEEPSEEK_API_KEY

截至 2026-05-30，DeepSeek 官方文档列出的模型名包括：

• deepseek-v4-flash
• deepseek-v4-pro
• deepseek-chat：兼容旧名，官方标注将在 2026-07-24 废弃。
• deepseek-reasoner：兼容旧名，官方标注将在 2026-07-24 废弃。

给普通软件配置 DeepSeek 时，一般这样填：

Provider: OpenAI-compatible
Base URL: https://api.deepseek.com
API key: <DEEPSEEK_API_KEY>
Model: deepseek-v4-pro

如果软件明确要求 Anthropic-compatible，例如某些 Claude API 风格工具，再用下面这组：

Provider: Anthropic-compatible
Base URL: https://api.deepseek.com/anthropic
API key: <DEEPSEEK_API_KEY>
Model: deepseek-v4-pro

curl

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Say hello in one sentence."}
    ]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Say hello in one sentence."},
    ],
)

print(response.choices[0].message.content)

DeepSeek 的 thinking、reasoning、tool calls、JSON output、context caching 等能力要看具体模型和客户端支持情况。普通软件接入时，先跑通最小聊天调用，再试这些高级能力。

OpenRouter

OpenRouter 是统一入口，一个 endpoint 后面接很多模型提供方。它的 HTTP API 是 OpenAI-compatible 风格：

Base URL: https://openrouter.ai/api/v1
Endpoint: /chat/completions
API key: OPENROUTER_API_KEY
Model: OpenRouter model slug

OpenRouter 的模型名是平台自己的 slug，不是上游厂商的原生模型名。常见几类写法：

openai/gpt-4.1
anthropic/claude-sonnet-4.5
google/gemini-2.5-pro
deepseek/deepseek-r1

这种 provider/model 是最普通的模型 ID。实际使用时直接从 OpenRouter 模型目录复制，不要凭记忆手写。

OpenRouter 还有几类特殊写法：

~openai/gpt-latest
~anthropic/claude-sonnet-latest

~author/family-latest 是 OpenRouter 的 latest alias，会路由到某个模型家族的最新版本。适合尝鲜和原型开发，不适合需要稳定复现的任务。

meta-llama/llama-3.2-3b-instruct:free

:free 是免费 variant 后缀，表示用这个模型的免费版本。免费模型通常有更低的速率限制和可用性限制。

openrouter/free

openrouter/free 不是具体模型，而是 Free Models Router，会从可用免费模型里自动挑一个满足请求要求的模型。适合测试和低频使用，不适合要求模型行为稳定的场景。

OpenRouter 也有过 :online 这类后缀用于联网搜索，但官方文档已经标注为 deprecated，推荐使用 openrouter:web_search server tool。普通软件配置里不建议优先用这种旧后缀。

给软件配置 OpenRouter 时，通常这样填：

Provider: OpenAI-compatible
Base URL: https://openrouter.ai/api/v1
API key: <OPENROUTER_API_KEY>
Model: openai/gpt-4.1

OpenRouter 支持可选的应用归因 header：

HTTP-Referer: <YOUR_SITE_URL>
X-OpenRouter-Title: <YOUR_SITE_NAME>

这些 header 不是鉴权必需项，主要用于调用来源统计和排行。个人配置软件时，一般只需要 base URL、API key、model。

curl

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [
      {"role": "user", "content": "Say hello in one sentence."}
    ]
  }'

Python requests

import json
import os
import requests

response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "model": "openai/gpt-4.1",
        "messages": [
            {"role": "user", "content": "Say hello in one sentence."},
        ],
    }),
)

print(response.json()["choices"][0]["message"]["content"])

Python OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-4.1",
    messages=[
        {"role": "user", "content": "Say hello in one sentence."},
    ],
)

print(response.choices[0].message.content)

给软件配置时怎么判断

很多软件的配置项名称不同，但含义基本类似：

API Provider / Provider / API Type
Base URL
API key
Model

按下面顺序填：

1. 先选 API 格式：优先选软件内置 provider；没有内置就选 OpenAI-compatible。
2. 填 base URL：DeepSeek 填 https://api.deepseek.com，OpenRouter 填 https://openrouter.ai/api/v1。
3. 填 API key：使用对应平台生成的 key。
4. 填模型名：DeepSeek 用官方模型名，OpenRouter 用模型目录里的 slug。
5. 保存后先发一句普通聊天。
6. 普通聊天成功后，再测试 stream、tool call、JSON output、长上下文等能力。

常见错误

401 / 403：

• API key 错误。
• key 没有权限。
• 软件把 key 放到了错误 header。

404：

• base URL 错误。
• 多写或少写了 /v1。
• 把 endpoint 当成 base URL 填了。

model not found：

• 模型名写错。
• OpenRouter 没用模型 slug。
• DeepSeek 旧模型名已废弃或服务商不再接受。

普通聊天可用，但 agent 不可用：

• 服务不支持 tool call。
• stream 实现不兼容。
• JSON schema、reasoning、thinking 等字段不兼容。
• 软件默认使用了该服务不支持的新 API。

参考

• DeepSeek API Docs
• DeepSeek Anthropic API
• OpenRouter Quickstart
• OpenRouter API Reference