词源探索 API 开发者文档

TIP

多页帮助中心已拆分：日常请从帮助中心首页进入各专题文档（大模型 API、生图、生视频、客户端与 CLI）。本文件保留为单页完整参考，便于全文搜索。

大模型 API
图像生成
视频生成
Cherry Studio · Claude Code · Codex · Gemini CLI
VS Code / Cursor · IntelliJ · OpenCode

最近更新：2026 年 10 月 17 日
词源探索是一个大模型 API 聚合平台。你只需要一个 API Key，就能用 OpenAI / Anthropic (Claude) / Google Gemini 三种兼容协议，调用 Claude、Gemini、Kimi、DeepSeek、GLM、Qwen、豆包 Seedance 等多家模型。

重要

API 网关地址

本文所有示例中的 API 网关地址为 https://ai.afp.net（与控制台一致）。若你的环境使用自定义域名，请以控制台显示为准。

同样，sk-xxxxxxxx 只表示 API Key 的格式，请换成你自己创建的令牌。

快速开始
认证
Base URL 与兼容协议
模型列表
OpenAI Chat Completions
OpenAI Responses
Anthropic Messages（Claude 原生）
Gemini 原生接口
流式输出（SSE）
多模态：图片输入
工具调用（Function Calling）
推理 / Thinking
图片生成
视频生成（豆包 Seedance）
Embeddings 向量嵌入
SDK 示例汇总
常见客户端接入
错误码与排障
令牌、分组与限流
计费说明
常见问题 FAQ

1. 快速开始

只要四步，就能发出第一个请求。

1.1 注册与登录

打开词源探索控制台 https://ai.afp.net，注册并登录账号。

1.2 充值

进入「钱包」或「充值」页面，选择在线支付，或者使用兑换码。余额会以「额度」的形式显示。各模型的单价请看控制台的 「模型广场 / 定价」 页面，见 §20 计费说明。

1.3 创建令牌（API Key）

进入 「令牌管理」，点击 「添加令牌」。
按需设置名称、过期时间、额度上限、令牌分组、可用模型范围和 IP 白名单。不确定时保持默认即可。
保存后，点击「复制」，得到形如 sk-xxxxxxxxxxxxxxxx 的密钥。

警告

API Key 就是你的付费凭证。不要把它写进前端代码、移动端安装包、截图、日志或公开的代码仓库。如果怀疑已经泄露，请立即在「令牌管理」中删除或禁用它，再重新创建。

1.4 发出第一个请求

bash

export CIYUAN_BASE_URL="https://ai.afp.net"   # 网关地址
export CIYUAN_API_KEY="sk-xxxxxxxx"                 # 换成你的令牌

curl "$CIYUAN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "用三句话介绍一下你自己"}
    ]
  }'

返回 JSON 中的 choices[0].message.content 就是模型的回答。之后的示例都假设你已经设置了 CIYUAN_BASE_URL 和 CIYUAN_API_KEY 这两个环境变量。

Python 版本：

python

# pip install -U openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CIYUAN_API_KEY"],
    base_url=os.environ["CIYUAN_BASE_URL"] + "/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "用三句话介绍一下你自己"}],
)
print(resp.choices[0].message.content)

2. 认证

所有协议共用同一个 API Key，只是请求头的写法不同：

协议	推荐请求头	也可以这样写
OpenAI 兼容（`/v1/chat/completions`、`/v1/responses`、`/v1/images/*`、`/v1/videos` 等）	`Authorization: Bearer sk-xxx`	—
Anthropic Messages（`/v1/messages`）	`x-api-key: sk-xxx`，同时加 `anthropic-version: 2023-06-01`	`Authorization: Bearer sk-xxx`
Gemini 原生（`/v1beta/models/...`）	`x-goog-api-key: sk-xxx`	URL 参数 `?key=sk-xxx`，或 `Authorization: Bearer sk-xxx`

补充说明：

每个令牌可以单独设置额度上限、过期时间、可用模型、IP 白名单和所属分组。触发这些限制时，请求会被拒绝，见 §18。
控制台登录状态、后台「系统访问令牌」只用于管理接口（/api/*），不能用来调用模型。调用模型请使用 sk- 开头的令牌。

3. Base URL 与兼容协议

协议	方法与路径	适用场景
OpenAI Chat Completions	`POST https://ai.afp.net/v1/chat/completions`	兼容性最好，推荐首选。所有文本模型都能用，大多数第三方工具也只支持这个接口
OpenAI Responses	`POST https://ai.afp.net/v1/responses`	新版 OpenAI 统一接口。能否使用取决于模型和渠道，接入前请先测试
Anthropic Messages	`POST https://ai.afp.net/v1/messages`	适合已有 Anthropic SDK 代码、Claude Code 等。建议只用于 Claude 系列模型
Gemini generateContent	`POST https://ai.afp.net/v1beta/models/{model}:generateContent`	适合已有 Google GenAI SDK 代码、Gemini CLI，以及 Gemini 图片生成
Gemini 流式	`POST https://ai.afp.net/v1beta/models/{model}:streamGenerateContent?alt=sse`	Gemini 原生流式输出
模型列表	`GET https://ai.afp.net/v1/models`	查询当前令牌可用的模型
图片生成	`POST https://ai.afp.net/v1/images/generations`	OpenAI 图片生成格式
视频生成（统一协议）	`POST https://ai.afp.net/v1/videos`，`GET https://ai.afp.net/v1/videos/{id}`	异步视频任务
视频生成（豆包原生格式）	`POST https://ai.afp.net/doubao/api/v3/contents/generations/tasks`	需要使用 Seedance 全部参数时
向量嵌入	`POST https://ai.afp.net/v1/embeddings`	文本向量化，需要平台上架嵌入模型

不同客户端的 Base URL 怎么填

不同 SDK 和工具对「Base URL」的理解不一样。最常见的三种写法如下：

写法	典型使用方
`https://ai.afp.net`	Anthropic SDK、Claude Code、Google GenAI SDK、Gemini CLI、Cherry Studio
`https://ai.afp.net/v1`	OpenAI 官方 SDK（Python / Node）、LobeChat、Cline（OpenAI Compatible）、Cursor、LangChain
`https://ai.afp.net/v1/chat/completions`	少数要求填写完整接口地址的工具

TIP

如果一种写法报 404，就依次换成另外两种。只要多出或少了一个 /v1，就会导致路径错误。

模型和协议可以交叉使用吗？

可以。平台会在协议之间转换格式，所以你可以用 OpenAI 格式调用 Claude 或 Gemini，也可以用 Claude 格式调用部分非 Claude 模型。不过转换并不是对每个字段都无损：

Claude 系列：优先使用 /v1/messages 或 /v1/chat/completions。
Gemini 系列：优先使用 /v1/chat/completions 或 Gemini 原生接口。图片生成请使用 Gemini 原生接口。
Kimi / DeepSeek / GLM / Qwen：使用 /v1/chat/completions。
Seedance 视频：只能使用视频任务接口，见 §14。

4. 模型列表

4.1 查询接口

bash

curl "$CIYUAN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

返回 OpenAI 格式的列表：

json

{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-4-6", "object": "model", "owned_by": "..."},
    {"id": "gemini-3.1-pro", "object": "model", "owned_by": "..."}
  ]
}

返回的模型受到 令牌可用模型范围 和 令牌所属分组 的限制。以接口实际返回为准。

使用 Gemini SDK 时，也可以用原生格式查询：GET https://ai.afp.net/v1beta/models（请求头为 x-goog-api-key）。

4.2 当前模型一览

模型会持续上新和下线，下表只是截至本文更新时的快照。价格请以控制台「模型广场 / 定价」页面为准，本文不列出价格。

Claude（Anthropic）

模型 ID	说明
`claude-opus-5-5`	Opus 系列旗舰
`claude-opus-5`	Opus 5
`claude-opus-4-8`	Opus 4.8
`claude-opus-4-7`	Opus 4.7
`claude-opus-4-6`	Opus 4.6
`claude-opus-4-6-thinking`	Opus 4.6 默认开启扩展思考的版本，见 §12
`claude-sonnet-5`	Sonnet 5
`claude-sonnet-4-6`	Sonnet 4.6，日常开发推荐
`claude-sonnet-4-5-20250929`	Sonnet 4.5（带日期的固定版本）
`claude-haiku-4-5`	Haiku 4.5，低延迟、低成本
`claude-haiku-4-5-20251001`	Haiku 4.5（带日期的固定版本）
`claude-fable-5`	Fable 5
`claude-fable-5-1`	Fable 5.1

Gemini（Google）

模型 ID	说明
`gemini-3.1-pro`	Gemini 3.1 Pro
`gemini-3.1-pro-preview`	Gemini 3.1 Pro 预览版
`gemini-3.7-flash`	Gemini 3.7 Flash
`gemini-3.6-flash`	Gemini 3.6 Flash
`gemini-3.5-flash`	Gemini 3.5 Flash
`gemini-3.5-flash-lite`	Gemini 3.5 Flash-Lite
`gemini-3.1-flash-lite`	Gemini 3.1 Flash-Lite
`gemini-2.5-pro`	Gemini 2.5 Pro
`gemini-2.5-flash-lite`	Gemini 2.5 Flash-Lite
`gemini-3-pro-image`	图片生成 / 编辑，见 §13
`gemini-3.1-flash-image`	图片生成 / 编辑（Flash 档）

Kimi（月之暗面）

模型 ID	说明
`kimi-k3`	Kimi K3
`kimi-k3-usd`	Kimi K3 的另一个计费 / 渠道版本，具体差异见控制台说明

DeepSeek

模型 ID	说明
`deepseek-v4-pro-0813`	DeepSeek V4 Pro
`deepseek-v4-flash`	DeepSeek V4 Flash
`deepseek-v4-1-flash-260910`	DeepSeek V4.1 Flash

GLM（智谱）

模型 ID	说明
`glm-5.3`	GLM-5.3
`glm-5.3-flash`	GLM-5.3 Flash
`glm-5.2`	GLM-5.2

Qwen（通义千问）

模型 ID	说明
`qwen3.8-max`	Qwen3.8 Max
`qwen3.8-flash`	Qwen3.8 Flash

豆包 Seedance（视频生成）

模型 ID	说明
`doubao-seedance-2-5-260628`	Seedance 2.5
`doubao-seedance-2-0-260128`	Seedance 2.0 标准版
`doubao-seedance-2-0-fast-260128`	Seedance 2.0 Fast（更快，分辨率上限较低）
`doubao-seedance-2-0-mini-260615`	Seedance 2.0 Mini（更轻量，分辨率上限较低）

INFO

并非每个模型都支持图片输入、工具调用、推理参数或 /v1/responses。正式集成前，请先用目标模型发一次最小请求。控制台「模型广场」通常会标出每个模型支持的端点类型。

5. OpenAI Chat Completions

POST https://ai.afp.net/v1/chat/completions

5.1 基础请求

bash

curl "$CIYUAN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的技术助手。"},
      {"role": "user", "content": "解释一下什么是 SSE"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

5.2 响应示例

json

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1792000000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "SSE（Server-Sent Events）是……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 25, "completion_tokens": 180, "total_tokens": 205}
}

5.3 常用字段

字段	说明
`model`	必填，模型 ID
`messages`	必填，对话消息数组，`role` 可以是 `system` / `user` / `assistant` / `tool`
`stream`	是否开启流式输出，见 §9
`stream_options`	设为 `{"include_usage": true}` 时，流式结束前会多返回一个带 `usage` 的块
`max_tokens` / `max_completion_tokens`	最大输出 token 数。推理模型的思考过程也会占用这个额度
`temperature` / `top_p`	采样参数。部分推理模型不支持
`tools` / `tool_choice`	工具调用，见 §11
`response_format`	结构化输出，例如 `{"type": "json_object"}`。支持情况取决于模型
`reasoning_effort`	推理强度 `low` / `medium` / `high`。仅部分模型支持，见 §12
`stop` / `seed` / `n` / `presence_penalty` / `frequency_penalty`	标准 OpenAI 参数。上游不支持的参数可能被忽略，也可能报错

5.4 `finish_reason` 含义

值	含义
`stop`	正常结束
`length`	达到了 `max_tokens` 上限。推理模型返回空内容时，通常就是这个原因
`tool_calls`	模型要求调用工具
`content_filter`	内容被安全策略过滤

6. OpenAI Responses

POST https://ai.afp.net/v1/responses

平台支持 OpenAI Responses 协议。请求体用 input 代替 messages，用 instructions 代替 system 消息。

INFO

Responses 是 OpenAI 的新协议。某个模型能否通过 Responses 调用，取决于平台给它配置的渠道。 如果你调用的是 Claude、Gemini、Kimi 等非 OpenAI 模型，又没有特别理由，请优先使用 /v1/chat/completions 或厂商原生协议。接入前请用目标模型做一次最小测试，返回 4xx 时就换回 Chat Completions。

bash

curl "$CIYUAN_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "instructions": "你是一个简洁的技术助手。",
    "input": "用三句话介绍词源探索",
    "max_output_tokens": 1024
  }'

python

resp = client.responses.create(
    model="claude-sonnet-4-6",
    input="用三句话介绍词源探索",
)
print(resp.output_text)

字段	说明
`model`	必填
`input`	必填，可以是字符串，也可以是结构化的消息数组
`instructions`	系统级指令
`stream`	流式输出，返回语义化的 SSE 事件，例如 `response.output_text.delta`
`max_output_tokens`	最大输出 token 数
`reasoning`	例如 `{"effort": "high"}`，取决于模型
`tools`	工具定义（Responses 格式，字段平铺，不嵌套 `function`）

判断是否完成：检查返回的 status。completed 表示正常结束；incomplete 表示中途停止，原因见 incomplete_details.reason，常见值是 max_output_tokens。

7. Anthropic Messages（Claude 原生）

POST https://ai.afp.net/v1/messages

适合已有 Anthropic SDK 代码、Claude Code 和各类 Agent 框架。请求体完全按照 Anthropic Messages API 编写。

bash

curl "$CIYUAN_BASE_URL/v1/messages" \
  -H "x-api-key: $CIYUAN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "system": "你是一个资深的 Go 工程师。",
    "messages": [
      {"role": "user", "content": "goroutine 泄漏一般怎么排查？"}
    ]
  }'

响应示例：

json

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [{"type": "text", "text": "排查 goroutine 泄漏可以从……"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 30, "output_tokens": 420}
}

Anthropic 格式与 OpenAI 格式的主要区别

项目	Anthropic Messages	OpenAI Chat Completions
`max_tokens`	必填	可选
系统提示词	顶层 `system` 字段	`role: "system"` 消息
图片	`{"type":"image","source":{...}}`	`{"type":"image_url","image_url":{...}}`
工具 schema	`input_schema`	`function.parameters`
停止原因	`stop_reason`（`end_turn` / `max_tokens` / `tool_use`）	`finish_reason`
鉴权	`x-api-key` + `anthropic-version`	`Authorization: Bearer`

Prompt 缓存：如果模型和渠道支持，可以在 system 或消息块上加 "cache_control": {"type": "ephemeral"}。命中缓存时，usage 中会出现 cache_read_input_tokens / cache_creation_input_tokens，计费也随之变化，见 §20。

8. Gemini 原生接口

Base URL 为 https://ai.afp.net，路径和 Google Gemini API 一致：

非流式：POST https://ai.afp.net/v1beta/models/{model}:generateContent
流式：POST https://ai.afp.net/v1beta/models/{model}:streamGenerateContent?alt=sse

bash

curl "$CIYUAN_BASE_URL/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {"parts": [{"text": "你是一个简洁的助手。"}]},
    "contents": [
      {"role": "user", "parts": [{"text": "为什么海水是咸的？"}]}
    ],
    "generationConfig": {"temperature": 0.7, "maxOutputTokens": 2048}
  }'

Python（Google GenAI SDK）：

python

# pip install -U google-genai
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["CIYUAN_API_KEY"],
    http_options=types.HttpOptions(base_url=os.environ["CIYUAN_BASE_URL"]),
)

resp = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="为什么海水是咸的？",
)
print(resp.text)

INFO

平台暂不支持 :countTokens，调用会返回 404。需要估算 token 时，请参考响应中的 usageMetadata。

9. 流式输出（SSE）

设置 stream: true 后，接口返回的是 Server-Sent Events 事件流，而不是一个完整的 JSON。客户端要逐行读取以 data: 开头的事件。

9.1 OpenAI Chat Completions 流式

bash

curl -N "$CIYUAN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "写一首关于秋天的五言绝句"}]
  }'

事件格式：

text

data: {"id":"chatcmpl-xxx","choices":[{"index":0,"delta":{"role":"assistant","content":"秋"}}]}

data: {"id":"chatcmpl-xxx","choices":[{"index":0,"delta":{"content":"风"}}]}

data: {"id":"chatcmpl-xxx","choices":[],"usage":{"prompt_tokens":20,"completion_tokens":28,"total_tokens":48}}

data: [DONE]

Python：

python

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "写一首关于秋天的五言绝句"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:  # 最后一个块
        print("\n用量：", chunk.usage)

Node.js：

javascript

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "写一首关于秋天的五言绝句" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

9.2 Anthropic 流式

在 /v1/messages 请求体中加 "stream": true，返回 Anthropic 标准事件：message_start → content_block_start → 多个 content_block_delta → content_block_stop → message_delta → message_stop。用 SDK 读取最方便：

python

with claude.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "讲一个程序员笑话"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

9.3 Gemini 流式

使用 :streamGenerateContent?alt=sse。每个 data: 都是一个部分的 GenerateContentResponse。

9.4 注意事项

curl 要加 -N，关闭缓冲。
Nginx 等反向代理需要关闭缓冲（proxy_buffering off;），否则内容会攒在一起才输出。
长时间推理时，流中可能有一段时间没有正文。请把客户端的读超时设得长一些，建议不少于 300 秒。

10. 多模态：图片输入

本节讲的是让模型 看图、理解图片、提取图中文字。如果要 生成图片，请看 §13。

支持图片输入的模型主要是 Claude 系列和 Gemini 系列（不含 *-image 生图模型）。Kimi、Qwen、GLM 等模型是否支持视觉输入，请以模型广场标注为准。

三种协议的图片字段各不相同：

协议	写法
Chat Completions	`messages[].content[]` 中写 `{"type":"image_url","image_url":{"url":"..."}}`
Responses	`input[].content[]` 中写 `{"type":"input_image","image_url":"..."}`
Anthropic Messages	`messages[].content[]` 中写 `{"type":"image","source":{...}}`
Gemini 原生	`parts[]` 中写 `{"inlineData":{"mimeType":"image/png","data":"<base64>"}}`

10.1 Chat Completions

bash

curl "$CIYUAN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片，并提取图中的文字"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
      ]
    }]
  }'

也可以用 Base64 Data URL 传本地图片：

json

{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,BASE64_IMAGE_DATA"}}

Python 读取本地图片：

python

import base64
with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么？"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}},
        ],
    }],
)

10.2 Anthropic Messages

json

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "描述这张图片"},
      {"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}}
    ]
  }]
}

Base64 写法：

json

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

10.3 图片输入排障

先确认模型支持视觉输入。
图片 URL 必须能从公网直接访问，不能需要登录或带防盗链。拿不准时改用 Data URL。
图片太大可能导致请求体超限（413）或费用增加，建议先压缩到长边 2000px 以内。

11. 工具调用（Function Calling）

11.1 OpenAI 格式（完整往返示例）

python

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的实时天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名，例如 北京"}
            },
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "北京现在天气怎么样？"}]

# 第一轮：模型决定调用工具
resp = client.chat.completions.create(
    model="claude-sonnet-4-6", messages=messages, tools=tools, tool_choice="auto"
)
msg = resp.choices[0].message
messages.append(msg)

if msg.tool_calls:
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = {"city": args["city"], "weather": "晴", "temp_c": 18}  # 换成你的真实实现
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

    # 第二轮：把工具结果交给模型，生成最终回答
    final = client.chat.completions.create(
        model="claude-sonnet-4-6", messages=messages, tools=tools
    )
    print(final.choices[0].message.content)

tool_choice 可选值："auto"（默认）、"none"、"required"，或者 {"type":"function","function":{"name":"get_weather"}}（强制调用指定函数）。

11.2 Anthropic 格式

bash

curl "$CIYUAN_BASE_URL/v1/messages" \
  -H "x-api-key: $CIYUAN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "查询指定城市的实时天气",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }],
    "messages": [{"role": "user", "content": "北京现在天气怎么样？"}]
  }'

当返回 stop_reason: "tool_use" 时，从 content 中取出 type: "tool_use" 块（包含 id、name、input）。执行工具后，在下一轮的 user 消息中回传结果：

json

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_xxx", "content": "{\"weather\":\"晴\",\"temp_c\":18}"}
]}

11.3 小贴士

工具调用的支持程度因模型而异。Claude、Gemini、Kimi、DeepSeek、GLM、Qwen 的主力模型一般都支持。
parameters / input_schema 必须是合法的 JSON Schema。没有参数时，写 {"type":"object","properties":{}}。
并行工具调用时，tool_calls 中可能同时有多个调用，需要逐一回传结果。

12. 推理 / Thinking

推理模型会先思考、再回答。思考过程要消耗 token，一般按输出计费，而且会占用 max_tokens 额度。

12.1 Claude 扩展思考

方式一：Anthropic 原生参数（推荐）

json

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": {"type": "enabled", "budget_tokens": 8000},
  "messages": [{"role": "user", "content": "证明根号 2 是无理数"}]
}

budget_tokens 必须小于 max_tokens，并且不低于 1024。
返回的 content 中会先出现 type: "thinking" 块，然后才是 type: "text" 块。
开启 thinking 后，不要再设置 temperature、top_k 等采样参数。

方式二：直接使用 -thinking 模型

claude-opus-4-6-thinking 默认开启思考，用任何协议调用都可以。

bash

curl "$CIYUAN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6-thinking",
    "max_tokens": 16000,
    "messages": [{"role": "user", "content": "证明根号 2 是无理数"}]
  }'

通过 Chat Completions 调用时，思考内容一般放在 choices[0].message.reasoning_content 中，流式输出时放在 delta.reasoning_content 中。正文仍然在 content 中。

12.2 Gemini 思考

Gemini 2.5 / 3.x 系列默认会思考。

Chat Completions：可以传 "reasoning_effort": "low" | "medium" | "high"，平台会转换成 Gemini 的思考配置。具体映射关系取决于模型。
Gemini 原生：在 generationConfig.thinkingConfig 中控制：

json

{
  "contents": [{"role": "user", "parts": [{"text": "一步步算 37 × 43"}]}],
  "generationConfig": {
    "thinkingConfig": {"thinkingBudget": 2048, "includeThoughts": true}
  }
}

Gemini 3 系列也支持 "thinkingLevel": "low" | "high"。支持的字段以 Google 官方文档和实际返回为准。

12.3 DeepSeek / Kimi / GLM / Qwen

这些模型通过 /v1/chat/completions 调用。如果模型有思考过程，一般返回在 reasoning_content 字段中。是否支持 reasoning_effort 或开关思考的参数，以各模型的说明为准。

12.4 推理模型的常见坑

返回空内容：多半是 max_tokens 设得太小，全被思考过程用完了，此时 finish_reason 为 length。调大 max_tokens 或去掉这个参数即可。
参数报错：推理模型对 temperature、top_p、presence_penalty、frequency_penalty、logprobs 等参数更严格。报错时先删掉这些采样参数，只保留模型、消息和 token 上限。
首字慢：思考需要时间。非流式请求要等思考完成才返回，体验要求高的场景请使用流式。

13. 图片生成

13.1 Gemini 生图（推荐使用原生接口）

gemini-3-pro-image 和 gemini-3.1-flash-image 都是 Gemini 原生的「文 + 图」多模态输出模型。建议通过 Gemini 原生 generateContent 调用：

bash

curl "$CIYUAN_BASE_URL/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一只坐在窗边看雨的橘猫，水彩风格"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

返回的 candidates[0].content.parts[] 中，带 inlineData（mimeType + Base64 data）的部分就是图片。Python 示例：

python

import base64
from google.genai import types

resp = client.models.generate_content(
    model="gemini-3-pro-image",
    contents="一只坐在窗边看雨的橘猫，水彩风格",
    config=types.GenerateContentConfig(response_modalities=["TEXT", "IMAGE"]),
)
for part in resp.candidates[0].content.parts:
    if part.inline_data:
        with open("cat.png", "wb") as f:
            f.write(part.inline_data.data)  # SDK 已完成 Base64 解码
    elif part.text:
        print(part.text)

改图 / 参考图：在 parts 中同时放一个 inlineData 图片和一段文字指令（例如「把背景换成雪景」）即可。

INFO

也可以用 /v1/chat/completions 调用这两个模型，但生成的图片会以什么形式放进 content（例如 Markdown 图片或 Data URL），取决于平台版本和渠道配置。批量生产请使用原生接口。

13.2 OpenAI 图片接口

平台同样提供 OpenAI 格式的图片接口：

生成：POST https://ai.afp.net/v1/images/generations
编辑：POST https://ai.afp.net/v1/images/edits（multipart/form-data 或 JSON）

bash

curl "$CIYUAN_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<控制台标注支持 images/generations 的模型>",
    "prompt": "一只坐在窗边看雨的橘猫，水彩风格",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

图片接口在请求内同步等待生成完成，结果只在这次响应中返回，事后无法再查询，请及时保存。耗时过长时可能返回 504 task_timeout。能用于该接口的模型，以模型广场的「支持端点」标注为准。

14. 视频生成（豆包 Seedance）

视频生成是 异步任务：先提交任务，拿到任务 ID，然后轮询任务状态，完成后下载视频。任务 ID 由平台统一分配，查询时必须使用同一个令牌所属的账号。

平台提供两种接入格式，任选一种：

格式	提交	查询	适用场景
统一视频协议（OpenAI Video 风格）	`POST /v1/videos`	`GET /v1/videos/{task_id}`；下载用 `GET /v1/videos/{task_id}/content`	想用一套代码对接多家视频模型
豆包原生格式（火山方舟风格）	`POST /doubao/api/v3/contents/generations/tasks`	`GET /doubao/api/v3/contents/generations/tasks/{task_id}`	需要使用 Seedance 全部参数，例如首尾帧、参考视频 / 音频、生成音频、草稿等

兼容旧版：POST /v1/video/generations，并用 GET /v1/video/generations/{task_id} 查询，也可以使用。新项目建议用上表中的两种方式。

14.1 统一视频协议

提交任务（文生视频）

bash

curl "$CIYUAN_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "海边日出，镜头缓慢推进，海浪轻拍礁石，电影感",
    "duration": 5,
    "resolution": "720p",
    "metadata": {"ratio": "16:9"}
  }'

图生视频：增加 "image": "https://example.com/first_frame.png"；多张参考图用 "images": [...]。

返回的对象中带有任务 id，以及 status（例如 queued）。

查询任务

bash

curl "$CIYUAN_BASE_URL/v1/videos/<task_id>" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

status 依次经过 queued → in_progress → completed（或 failed）。

下载视频（任务完成后）

bash

curl -L "$CIYUAN_BASE_URL/v1/videos/<task_id>/content" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -o output.mp4

下载接口支持 Range 请求头，可以分段下载或断点续传。

14.2 豆包原生格式（参数最全）

提交任务

bash

curl "$CIYUAN_BASE_URL/doubao/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "小女孩在麦田里奔跑，风吹动麦浪，夕阳逆光"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first_frame.png"}, "role": "first_frame"}
    ],
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'

json

{"id": "task_xxxxxxxx"}

查询任务

bash

curl "$CIYUAN_BASE_URL/doubao/api/v3/contents/generations/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

json

{
  "id": "task_xxxxxxxx",
  "status": "succeeded",
  "content": {"video_url": "https://.../output.mp4"},
  "duration": 5,
  "resolution": "1080p"
}

失败时：{"status": "failed", "error": {"code": "...", "message": "..."}}

常用参数

字段	说明
`model`	必填，Seedance 模型 ID，见 §4.2
`content`	必填，数组。元素类型可以是 `text`（提示词）、`image_url`（参考图 / 首帧 / 尾帧，用 `role` 区分，例如 `first_frame` / `last_frame` / `reference_image`）、`video_url`、`audio_url`、`draft_task`
`duration`	时长（秒）。`-1` 表示由模型自动选择。可选范围取决于模型
`resolution`	例如 `480p` / `720p` / `1080p`。2.0 Fast 和 2.0 Mini 最高 720p；标准版和 2.5 支持更高分辨率，具体以模型说明为准
`ratio`	画面比例，例如 `16:9`、`9:16`、`1:1`、`adaptive`
`generate_audio`	是否同时生成音频（取决于模型）
`seed` / `camera_fixed` / `watermark` / `return_last_frame`	随机种子 / 固定镜头 / 水印 / 返回尾帧
`draft`	草稿模式。之后可以用 `{"type":"draft_task","draft_task":{"id":"<平台任务ID>"}}` 基于草稿生成正式视频
`callback_url`	任务完成回调地址（可选）

部分平台版本也会提供不带 /doubao 前缀的同名路径 /api/v3/contents/generations/tasks，方便直接改火山方舟 SDK 的 Base URL。带前缀的路径兼容性最好。

14.3 Python 轮询示例（统一协议）

python

import os, time, requests

BASE = os.environ["CIYUAN_BASE_URL"]
H = {"Authorization": f"Bearer {os.environ['CIYUAN_API_KEY']}"}

task = requests.post(f"{BASE}/v1/videos", headers=H, json={
    "model": "doubao-seedance-2-0-mini-260615",
    "prompt": "一只柴犬在雪地里打滚，慢动作",
    "duration": 5,
    "resolution": "720p",
}).json()
task_id = task["id"]
print("任务已提交：", task_id)

while True:
    info = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H).json()
    status = info.get("status")
    print("状态：", status, info.get("progress", ""))
    if status in ("completed", "succeeded"):
        break
    if status == "failed":
        raise RuntimeError(info.get("error"))
    time.sleep(10)

with requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=H, stream=True) as r:
    r.raise_for_status()
    with open("output.mp4", "wb") as f:
        for chunk in r.iter_content(1 << 20):
            f.write(chunk)
print("已保存 output.mp4")

14.4 视频任务注意事项

视频生成通常需要几十秒到几分钟。轮询间隔建议 5～15 秒，不要高频请求。
上游返回的视频链接一般有有效期，请尽快下载或转存。
统一协议中各字段（duration、resolution、image 等）如何映射到厂商参数，由平台的视频插件负责。如果某个参数没有生效，请改用豆包原生格式。
视频按次或按秒计费，并可能随分辨率、时长、是否生成音频而变化，详见控制台定价页。

15. Embeddings 向量嵌入

POST https://ai.afp.net/v1/embeddings（OpenAI 格式）；Gemini 原生格式为 :embedContent / :batchEmbedContents。

bash

curl "$CIYUAN_BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<嵌入模型 ID>", "input": ["词源探索", "大模型 API 聚合"]}'

INFO

当前模型列表中暂时没有专门的嵌入模型。接口本身可以使用，等平台上架嵌入模型后即可调用。请以 /v1/models 的返回为准。

16. SDK 示例汇总

16.1 Python · OpenAI SDK

python

# pip install -U openai
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxxxxx", base_url="https://ai.afp.net/v1")

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

16.2 Node.js / TypeScript · OpenAI SDK

javascript

// npm i openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CIYUAN_API_KEY,
  baseURL: `${process.env.CIYUAN_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

16.3 Python · Anthropic SDK

python

# pip install -U anthropic
import anthropic

claude = anthropic.Anthropic(
    api_key="sk-xxxxxxxx",
    base_url="https://ai.afp.net",   # 注意：不要带 /v1，SDK 会自动拼接 /v1/messages
)

msg = claude.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)

16.4 Node.js · Anthropic SDK

javascript

// npm i @anthropic-ai/sdk
import Anthropic from "@anthropic-ai/sdk";

const claude = new Anthropic({
  apiKey: process.env.CIYUAN_API_KEY,
  baseURL: process.env.CIYUAN_BASE_URL, // 不带 /v1
});

const msg = await claude.messages.create({
  model: "claude-haiku-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});
console.log(msg.content[0].text);

16.5 Python · Google GenAI SDK

见 §8。要点是 http_options=types.HttpOptions(base_url="https://ai.afp.net")，后面不要带 /v1beta。

16.6 LangChain

python

# pip install -U langchain-openai
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="qwen3.8-max",
    api_key="sk-xxxxxxxx",
    base_url="https://ai.afp.net/v1",
)
print(llm.invoke("你好").content)

16.7 环境变量方式

很多工具会自动读取以下环境变量：

bash

# OpenAI 生态
export OPENAI_API_KEY="sk-xxxxxxxx"
export OPENAI_BASE_URL="https://ai.afp.net/v1"

# Anthropic 生态
export ANTHROPIC_API_KEY="sk-xxxxxxxx"
export ANTHROPIC_BASE_URL="https://ai.afp.net"

17. 常见客户端接入

下文中的「API 地址」请填写词源探索的真实 https://ai.afp.net，「API Key」填写你的 sk- 令牌。

17.1 Claude Code

bash

npm install -g @anthropic-ai/claude-code

编辑 ~/.claude/settings.json（Windows 路径为 %USERPROFILE%\.claude\settings.json）：

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.afp.net",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

然后在项目目录下运行 claude。也可以在会话中用 /model 切换模型，例如 claude-opus-4-8。

如果遇到 invalid beta flag 一类的错误，可以加上环境变量 "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"。

17.2 Cherry Studio

打开「设置 → 模型服务」，点击底部「添加」。
提供商类型选 New API（没有这一项时选 OpenAI）。
API 地址填 https://ai.afp.net，API 密钥填 sk-xxxxxxxx。
点击「检查」测试连通性，再点击「管理」拉取并勾选模型。

如果想用 Claude 原生协议，可以再添加一个 Anthropic 类型的提供商，API 地址同样填 https://ai.afp.net。

17.3 Cursor

打开「Settings → Models」。
在 OpenAI API Key 处填入 sk-xxxxxxxx，打开 Override OpenAI Base URL，填入 https://ai.afp.net/v1。
点击「Add model」，手动添加模型 ID，例如 claude-sonnet-4-6、gemini-3.1-pro、kimi-k3，然后点击 Verify。

Cursor 的请求从 Cursor 服务器发出，所以 https://ai.afp.net 必须能从公网访问。Tab 补全等部分功能固定使用 Cursor 自己的模型，不会走自定义 Key。

17.4 Cline / Roo Code（VS Code）

方式 A：OpenAI Compatible

API Provider：OpenAI Compatible
Base URL：https://ai.afp.net/v1
API Key：sk-xxxxxxxx
Model ID：claude-sonnet-4-6（或其他模型）

方式 B：Anthropic（只用 Claude 时，原生支持 prompt 缓存和 thinking）

API Provider：Anthropic
勾选「Use custom base URL」，填 https://ai.afp.net
API Key：sk-xxxxxxxx

17.5 LobeChat

「设置 → 语言模型 → OpenAI」：

API Key：sk-xxxxxxxx
API 代理地址：https://ai.afp.net/v1
点击「获取模型列表」，勾选需要的模型，保存。

17.6 Gemini CLI

bash

npm install -g @google/gemini-cli

在 ~/.gemini/.env 或 ~/.env 中写入：

env

GOOGLE_GEMINI_BASE_URL=https://ai.afp.net
GEMINI_API_KEY=sk-xxxxxxxx
GEMINI_MODEL=gemini-3.1-pro

然后运行 gemini。

17.7 其他 OpenAI 兼容客户端

NextChat、Chatbox、ChatWise、Open WebUI、Dify、FastGPT、沉浸式翻译等工具，一般都选择「OpenAI / OpenAI 兼容」类型，再填 Base URL 和 Key。Base URL 怎么填，见 §3。

18. 错误码与排障

18.1 错误响应格式

OpenAI 兼容接口出错时返回：

json

{
  "error": {
    "message": "错误描述",
    "type": "new_api_error",
    "code": "model_not_found",
    "param": ""
  }
}

Anthropic 和 Gemini 原生接口会尽量返回各自协议的错误格式。排障时请记录完整的 error.message，以及响应头中的请求 ID（如果有）。

18.2 HTTP 状态码

状态码	含义	常见原因与处理
400	请求参数错误	JSON 格式错误、缺少必填字段（例如 Claude 的 `max_tokens`），或者模型不支持某个参数。先删掉可选参数，用最小请求复现
401	认证失败	Key 写错、缺少 `Bearer` 前缀、令牌已删除或已禁用。检查请求头写法
403	无权限或额度不足	账户余额不足、令牌额度已用完或已过期、令牌不允许使用该模型、IP 不在白名单中
404	路径不存在	Base URL 多了或少了 `/v1`，或者路径拼错。也可能是调用了平台未支持的接口（例如 Gemini `:countTokens`）
413	请求体过大	图片或文本太大，请压缩或拆分
429	请求过于频繁	触发了平台或上游限流，请用指数退避重试，见 §19
500	服务器内部错误	稍后重试。持续出现时请联系客服，并提供时间和模型
501	未实现	平台不支持该接口，例如 `/v1/files`、`/v1/fine-tunes`
502 / 503	上游不可用	上游渠道故障，或者当前分组下该模型没有可用渠道。稍后重试或换一个分组
504	超时	生成耗时过长，例如同步生图或长推理。改用流式或异步方式；图片任务可能仍在后台运行

18.3 典型报错与排查

报错关键字（示例）	原因	解决办法
`无效的令牌` / `invalid token`	Key 错误或已被删除	重新复制 Key，检查是否有多余空格
`额度不足` / `quota` / `insufficient`	账户余额或令牌额度不足	充值，或者提高该令牌的额度上限
`当前分组 xxx 下对于模型 xxx 无可用渠道` / `model_not_found`	模型名写错，或者令牌所属分组没有这个模型	用 `/v1/models` 核对模型名，或者在令牌设置中切换分组
`该令牌无权使用模型`	令牌设置了「可用模型」限制	编辑令牌，放开该模型
`max_tokens` 相关	Claude 缺少 `max_tokens`，或者 thinking 的 `budget_tokens` ≥ `max_tokens`	补上参数，或调大 `max_tokens`
返回空内容且 `finish_reason: length`	推理模型把 token 额度用在了思考上	调大 `max_tokens`
流式输出一次性才出来	代理或网关有缓冲	关闭反向代理缓冲；curl 加 `-N`

18.4 排障清单

先用本文 §1.4 的最小 curl 请求验证 Key 和 Base URL。
用 GET /v1/models 确认模型名完全一致，注意大小写和日期后缀。
去掉所有可选参数，逐个加回，找出不兼容的那个参数。
在控制台「使用日志」中查看这次请求的模型、用量、耗时和错误信息。
联系客服时请提供：时间（注明时区）、模型、接口路径、完整的错误信息、请求 ID。不要提供完整 Key。

19. 令牌、分组与限流

19.1 令牌（API Key）配置项

配置	作用
过期时间	到期后令牌自动失效
额度上限 / 无限额度	限制这个令牌最多能消费多少，适合分发给团队成员或子项目
可用模型	白名单内的模型才能调用
IP 白名单	只允许指定 IP 或网段使用
令牌分组	决定请求走哪一组渠道，以及使用哪个计费倍率

建议 每个应用或环境单独建一个令牌，用额度上限控制风险。

19.2 分组

平台把可用渠道和计费倍率按「分组」组织，例如默认分组、高可用分组、特价分组等，具体以控制台显示为准。

不同分组的 价格倍率、稳定性、可用模型 可能不同。
令牌可以指定分组。不指定时使用账户的默认分组。
如果某个模型在当前分组下没有可用渠道，会报「无可用渠道」，切换分组即可。

19.3 限流

平台可能按用户、令牌或模型限制请求频率；上游厂商也有自己的速率和并发限制。
超出限制时返回 429。请使用 指数退避 + 随机抖动 重试，例如等待 1s → 2s → 4s → 8s，最多重试 5 次，不要立即无限重试。
高并发、大批量任务请先评估用量。有更高配额需求时，可以联系客服开通。

python

import random, time
from openai import OpenAI, RateLimitError, APIStatusError

def chat_with_retry(client: OpenAI, max_retries: int = 5, **kwargs):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            pass
        except APIStatusError as e:
            if e.status_code < 500:
                raise  # 4xx（429 除外）重试也没用，直接抛出
        time.sleep(2 ** i + random.random())
    raise RuntimeError("重试次数用尽")

OpenAI 官方 SDK 自带重试，可以通过 OpenAI(max_retries=3, timeout=600) 配置次数和超时。

19.4 用量查询

控制台：「使用日志」可以查看每次请求的模型、token 用量、扣费和耗时；「数据看板」可以查看消耗趋势。
接口：用模型令牌调用 GET https://ai.afp.net/api/usage/token/（请求头 Authorization: Bearer sk-xxx），可以查询该令牌的额度使用情况。

20. 计费说明

本文不列出具体价格。所有价格以控制台「模型广场 / 定价」页面的实时数据为准。

20.1 计费方式

方式	常见于	说明
按量（token）计费	文本对话、推理、视觉理解	输入 token 和输出 token 分别计价，输出单价通常更高
按次计费	部分图片 / 视频模型	每次成功请求扣固定额度
按秒 / 按规格计费	视频生成	和时长、分辨率、是否生成音频等参数有关

20.2 影响费用的因素

模型单价：不同模型差别很大。Flash / Lite / Haiku 一类模型比 Pro / Opus 便宜得多。
分组倍率：不同分组的倍率不同，见 §19.2。
缓存：命中 prompt 缓存的输入 token 通常有折扣。写入缓存（Claude）可能按更高倍率计费。
推理 token：思考过程一般按输出 token 计费。
多模态输入：图片会换算成 token 计费，图片越大消耗越多。

20.3 扣费流程

请求开始时，平台会按预估用量预扣一部分额度。
请求结束后，按上游返回的实际 usage 结算，多退少补。
请求失败（例如 4xx 参数错误、上游报错）一般不扣费，或者退回预扣额度。流式请求中途断开时，按已经生成的内容计费。

每次请求的扣费明细都能在「使用日志」中查到。

20.4 省钱建议

简单任务用 *-flash / *-lite / claude-haiku-4-5，复杂任务再用 Pro / Opus。
控制上下文长度，及时裁剪历史消息。
长且固定的 system prompt 可以开启缓存（Claude 加 cache_control）。
给 max_tokens 设一个合理的上限，避免失控输出。
给每个令牌设置额度上限，防止 Key 泄露带来损失。

21. 常见问题 FAQ

Q：新项目该用 /v1/chat/completions 还是 /v1/responses？ A：在词源探索上，优先用 /v1/chat/completions，它对所有模型的兼容性最好。只有在确认目标模型支持 Responses，并且确实需要 Responses 特性时，再用 /v1/responses。

Q：用 OpenAI SDK 能调用 Claude 和 Gemini 吗？ A：可以。只要把 model 换成 claude-* 或 gemini-*，平台会自动转换协议。需要使用 Claude 或 Gemini 的独有特性（例如 Claude 的 cache_control、Gemini 的原生生图）时，建议使用原生协议。

Q：为什么问模型「你是谁」，它答的和模型名不一致？ A：模型对自己身份的认识来自训练数据，而训练数据通常早于模型发布，所以它可能不知道自己的正式名称。这不代表调用的模型不对。如果需要它正确报出身份，请在 system prompt 中写明。

Q：控制台显示有余额，为什么 API 提示额度不足？ A：请检查 令牌本身的额度上限 是否已经用完。账户余额和令牌额度是两回事。

Q：图片输入没有效果？ A：确认模型支持视觉输入；图片 URL 能从公网访问（拿不准就改用 Data URL）；字段写法和协议对应（见 §10）。不要把生图接口的参数传给对话接口。

Q：为什么流式响应不能直接 JSON.parse？ A：流式响应是 SSE 事件流，要按行读取 data: 事件，再分别解析，遇到 data: [DONE] 时结束。

Q：视频任务提交成功，但一直查询不到结果？ A：视频生成需要时间，请耐心轮询。如果长时间停在 queued，可能是上游在排队。failed 时请查看 error.message。查询时要用 同一账号下的令牌，并使用平台返回的任务 ID。

Q：claude-sonnet-4-5-20250929 和 claude-sonnet-4-6 有什么区别？ A：它们是不同的模型版本。带日期后缀的是固定快照，行为更稳定，适合生产环境锁定版本；不带日期的通常指向该系列推荐使用的版本。

Q：kimi-k3 和 kimi-k3-usd 选哪个？ A：两者是同一模型的不同计费或渠道版本。请在控制台定价页比较价格和说明后选择。

Q：支持文件上传、微调和 Assistants 吗？ A：不支持。/v1/files、/v1/fine-tunes 等接口会返回 501。需要处理文档时，请把内容提取为文本，或者以图片形式放进消息中。

Q：数据会被保存吗？ A：平台负责转发请求，并记录计费所需的用量日志（模型、token 数、耗时等）。具体的数据处理方式请以平台的《隐私政策》和《用户协议》为准。

附录：接口速查

功能	方法	路径	鉴权
模型列表	GET	`/v1/models`	Bearer
对话补全	POST	`/v1/chat/completions`	Bearer
Responses	POST	`/v1/responses`	Bearer
Claude Messages	POST	`/v1/messages`	x-api-key / Bearer
Gemini 生成	POST	`/v1beta/models/{model}:generateContent`	x-goog-api-key / `?key=`
Gemini 流式	POST	`/v1beta/models/{model}:streamGenerateContent?alt=sse`	同上
图片生成	POST	`/v1/images/generations`	Bearer
图片编辑	POST	`/v1/images/edits`	Bearer
视频提交（统一）	POST	`/v1/videos`	Bearer
视频查询（统一）	GET	`/v1/videos/{task_id}`	Bearer
视频下载	GET	`/v1/videos/{task_id}/content`	Bearer
视频提交（豆包原生）	POST	`/doubao/api/v3/contents/generations/tasks`	Bearer
视频查询（豆包原生）	GET	`/doubao/api/v3/contents/generations/tasks/{task_id}`	Bearer
向量嵌入	POST	`/v1/embeddings`	Bearer
令牌用量	GET	`/api/usage/token/`	Bearer（模型令牌）

词源探索 · 如有疑问，请通过控制台联系客服。

词源探索 API 开发者文档 ​

目录 ​

1. 快速开始 ​

1.1 注册与登录 ​

1.2 充值 ​

1.3 创建令牌（API Key） ​

1.4 发出第一个请求 ​

2. 认证 ​

3. Base URL 与兼容协议 ​

不同客户端的 Base URL 怎么填 ​

模型和协议可以交叉使用吗？ ​

4. 模型列表 ​

4.1 查询接口 ​

4.2 当前模型一览 ​

Claude（Anthropic） ​

Gemini（Google） ​

Kimi（月之暗面） ​

DeepSeek ​

GLM（智谱） ​

Qwen（通义千问） ​

豆包 Seedance（视频生成） ​

5. OpenAI Chat Completions ​

5.1 基础请求 ​

5.2 响应示例 ​

5.3 常用字段 ​

5.4 finish_reason 含义 ​

6. OpenAI Responses ​

7. Anthropic Messages（Claude 原生） ​

Anthropic 格式与 OpenAI 格式的主要区别 ​

8. Gemini 原生接口 ​

9. 流式输出（SSE） ​

9.1 OpenAI Chat Completions 流式 ​

9.2 Anthropic 流式 ​

9.3 Gemini 流式 ​

9.4 注意事项 ​

10. 多模态：图片输入 ​

10.1 Chat Completions ​

10.2 Anthropic Messages ​

10.3 图片输入排障 ​

11. 工具调用（Function Calling） ​

11.1 OpenAI 格式（完整往返示例） ​

11.2 Anthropic 格式 ​

11.3 小贴士 ​

12. 推理 / Thinking ​

12.1 Claude 扩展思考 ​

12.2 Gemini 思考 ​

12.3 DeepSeek / Kimi / GLM / Qwen ​

12.4 推理模型的常见坑 ​

13. 图片生成 ​

13.1 Gemini 生图（推荐使用原生接口） ​

13.2 OpenAI 图片接口 ​

14. 视频生成（豆包 Seedance） ​

14.1 统一视频协议 ​

14.2 豆包原生格式（参数最全） ​

14.3 Python 轮询示例（统一协议） ​

14.4 视频任务注意事项 ​

15. Embeddings 向量嵌入 ​

16. SDK 示例汇总 ​

16.1 Python · OpenAI SDK ​

16.2 Node.js / TypeScript · OpenAI SDK ​

16.3 Python · Anthropic SDK ​

16.4 Node.js · Anthropic SDK ​

16.5 Python · Google GenAI SDK ​

16.6 LangChain ​

16.7 环境变量方式 ​

17. 常见客户端接入 ​

17.1 Claude Code ​

17.2 Cherry Studio ​

17.3 Cursor ​

17.4 Cline / Roo Code（VS Code） ​

17.5 LobeChat ​

17.6 Gemini CLI ​

17.7 其他 OpenAI 兼容客户端 ​

18. 错误码与排障 ​

18.1 错误响应格式 ​

18.2 HTTP 状态码 ​

18.3 典型报错与排查 ​

18.4 排障清单 ​

19. 令牌、分组与限流 ​

19.1 令牌（API Key）配置项 ​

词源探索 API 开发者文档

目录

1. 快速开始

1.1 注册与登录

1.2 充值

1.3 创建令牌（API Key）

1.4 发出第一个请求

2. 认证

3. Base URL 与兼容协议

不同客户端的 Base URL 怎么填

模型和协议可以交叉使用吗？

4. 模型列表

4.1 查询接口

4.2 当前模型一览

Claude（Anthropic）

Gemini（Google）

Kimi（月之暗面）

DeepSeek

GLM（智谱）

Qwen（通义千问）

豆包 Seedance（视频生成）

5. OpenAI Chat Completions

5.1 基础请求

5.2 响应示例

5.3 常用字段

5.4 `finish_reason` 含义

6. OpenAI Responses

7. Anthropic Messages（Claude 原生）

Anthropic 格式与 OpenAI 格式的主要区别

8. Gemini 原生接口

9. 流式输出（SSE）

9.1 OpenAI Chat Completions 流式

9.2 Anthropic 流式

9.3 Gemini 流式

9.4 注意事项

10. 多模态：图片输入

10.1 Chat Completions

10.2 Anthropic Messages

10.3 图片输入排障

11. 工具调用（Function Calling）

11.1 OpenAI 格式（完整往返示例）

11.2 Anthropic 格式

11.3 小贴士

12. 推理 / Thinking

12.1 Claude 扩展思考

12.2 Gemini 思考

12.3 DeepSeek / Kimi / GLM / Qwen

12.4 推理模型的常见坑

13. 图片生成

13.1 Gemini 生图（推荐使用原生接口）

13.2 OpenAI 图片接口

14. 视频生成（豆包 Seedance）

14.1 统一视频协议

14.2 豆包原生格式（参数最全）

14.3 Python 轮询示例（统一协议）

14.4 视频任务注意事项

15. Embeddings 向量嵌入

16. SDK 示例汇总

16.1 Python · OpenAI SDK

16.2 Node.js / TypeScript · OpenAI SDK

16.3 Python · Anthropic SDK

16.4 Node.js · Anthropic SDK

16.5 Python · Google GenAI SDK

16.6 LangChain

16.7 环境变量方式

17. 常见客户端接入

17.1 Claude Code

17.2 Cherry Studio

17.3 Cursor

17.4 Cline / Roo Code（VS Code）

17.5 LobeChat

17.6 Gemini CLI

17.7 其他 OpenAI 兼容客户端

18. 错误码与排障

18.1 错误响应格式

18.2 HTTP 状态码

18.3 典型报错与排查

18.4 排障清单

19. 令牌、分组与限流

19.1 令牌（API Key）配置项