大模型 API 接入指南

最近更新：2026 年 10 月 17 日（Asia/Shanghai）
关联：帮助中心 · 图像生成 · 视频生成 · 完整参考

本文说明如何把词源探索的文本对话、看图理解、工具调用、流式输出、推理思考接到你的应用。若要生成图片或视频，请分别阅读图像生成与视频生成。

1. 选择端点

在词源探索上，新项目优先使用 OpenAI Chat Completions（/v1/chat/completions）：对 Claude、Gemini、Kimi、DeepSeek、GLM、Qwen 等模型兼容性最好，第三方工具支持也最广。

端点	路径	适用场景
OpenAI Chat Completions（推荐首选）	`POST https://ai.afp.net/v1/chat/completions`	绝大多数应用、SDK、第三方客户端
OpenAI Responses	`POST https://ai.afp.net/v1/responses`	已确认目标模型支持 Responses 时；新协议，接入前请做最小测试
Anthropic Messages	`POST https://ai.afp.net/v1/messages`	已有 Anthropic SDK / Claude Code
Gemini 原生	`POST https://ai.afp.net/v1beta/models/{model}:generateContent`	已有 Google GenAI SDK / Gemini CLI；生图也推荐这条
Gemini 流式	`POST https://ai.afp.net/v1beta/models/{model}:streamGenerateContent?alt=sse`	Gemini 原生流式
模型列表	`GET https://ai.afp.net/v1/models`	查询当前令牌可用模型

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

协议	推荐请求头
OpenAI 兼容	`Authorization: Bearer sk-xxx`
Anthropic	`x-api-key: sk-xxx` + `anthropic-version: 2023-06-01`（也可用 Bearer）
Gemini	`x-goog-api-key: sk-xxx`（也可用 `?key=` 或 Bearer）

警告

API Key 在控制台「令牌管理」创建。不要写入前端、截图、日志或公开仓库。

Base URL 怎么填：

写法	典型使用方
`https://ai.afp.net`	Anthropic SDK、Claude Code、Google GenAI、Gemini CLI、Cherry Studio
`https://ai.afp.net/v1`	OpenAI 官方 SDK、Cursor、LangChain、多数「OpenAI Compatible」客户端
`https://ai.afp.net/v1/chat/completions`	少数要求填完整路径的工具

一种写法报 404 时，依次尝试另外两种——多或少一个 /v1 是最常见原因。

2. 查询模型

bash

export CIYUAN_BASE_URL="https://ai.afp.net"
export CIYUAN_API_KEY="sk-xxxxxxxx"

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

返回 OpenAI 格式列表。结果受令牌可用模型与令牌分组限制，以接口实际返回为准。Gemini SDK 也可用 GET https://ai.afp.net/v1beta/models（x-goog-api-key）。

当前模型一览（快照）

价格请以控制台「模型广场 / 定价」为准，本文不列单价。

Claude

模型 ID	说明
`claude-opus-5-5` / `claude-opus-5`	Opus 旗舰档
`claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6`	Opus 4.x
`claude-opus-4-6-thinking`	默认开启扩展思考
`claude-sonnet-5` / `claude-sonnet-4-6`	Sonnet；日常开发常用 `claude-sonnet-4-6`
`claude-sonnet-4-5-20250929`	带日期的固定快照
`claude-haiku-4-5` / `claude-haiku-4-5-20251001`	低延迟、低成本
`claude-fable-5` / `claude-fable-5-1`	Fable 系列

Gemini

模型 ID	说明
`gemini-3.1-pro` / `gemini-3.1-pro-preview`	Pro 档
`gemini-3.7-flash` / `gemini-3.6-flash` / `gemini-3.5-flash`	Flash 档
`gemini-3.5-flash-lite` / `gemini-3.1-flash-lite` / `gemini-2.5-flash-lite`	Lite 档
`gemini-2.5-pro`	2.5 Pro
`gemini-3-pro-image` / `gemini-3.1-flash-image`	图片生成 / 编辑，见图像生成文档

其他文本模型

家族	模型 ID
Kimi	`kimi-k3`、`kimi-k3-usd`（计费/渠道变体，差异见控制台）
DeepSeek	`deepseek-v4-pro-0813`、`deepseek-v4-flash`、`deepseek-v4-1-flash-260910`
GLM	`glm-5.3`、`glm-5.3-flash`、`glm-5.2`
Qwen	`qwen3.8-max`、`qwen3.8-flash`

视频模型见视频生成文档。并非每个模型都支持视觉、工具、推理或 Responses——集成前请对目标模型发一次最小请求。

3. OpenAI Chat Completions（推荐）

POST https://ai.afp.net/v1/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": "system", "content": "你是一个简洁的技术助手。"},
      {"role": "user", "content": "解释一下什么是 SSE"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

响应中 choices[0].message.content 为回答；usage 为用量。

图片输入（看图，不是生图）

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"}}
      ]
    }]
  }'

本地图可用 Data URL：data:image/jpeg;base64,...。Claude、Gemini 主力文本模型通常支持视觉；Kimi / Qwen / GLM 请以模型广场标注为准。

工具调用

python

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

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

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"，或强制指定函数名。

流式输出

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": "写一首关于秋天的五言绝句"}]
  }'

返回 SSE：data: {...} 行，以 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)

常用字段

字段	说明
`model`	必填
`messages`	必填；`role` 可为 `system` / `user` / `assistant` / `tool`
`stream` / `stream_options`	流式；`include_usage` 可在末块带回用量
`max_tokens` / `max_completion_tokens`	输出上限；推理思考也会占用
`temperature` / `top_p`	采样；部分推理模型不支持
`tools` / `tool_choice`	工具调用
`response_format`	如 `{"type":"json_object"}`，视模型而定
`reasoning_effort`	`low` / `medium` / `high`，部分模型支持

finish_reason：stop 正常结束；length 触顶；tool_calls 要调工具；content_filter 被过滤。

4. OpenAI Responses

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

请求体用 input 代替 messages，用 instructions 代替 system。

INFO

某个模型能否走 Responses，取决于平台渠道配置。调用 Claude / Gemini / Kimi 等非 OpenAI 模型时，若无特别理由，请优先 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 事件）
`max_output_tokens`	输出上限
`reasoning`	如 `{"effort":"high"}`
`tools`	Responses 格式工具（字段平铺）

完成状态看 status：completed 正常；incomplete 见 incomplete_details.reason。

图片输入（Responses）： input[].content[] 中使用 {"type":"input_image","image_url":"..."}。

5. Anthropic Messages

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

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 泄漏一般怎么排查？"}
    ]
  }'

项目	Anthropic	Chat Completions
`max_tokens`	必填	可选
系统提示	顶层 `system`	`role: "system"`
图片	`type: "image"` + `source`	`type: "image_url"`
工具 schema	`input_schema`	`function.parameters`
停止原因	`stop_reason`	`finish_reason`

图片 URL 示例：{"type":"image","source":{"type":"url","url":"https://example.com/a.png"}}；Base64：source.type = "base64" 并带 media_type / data。

工具：stop_reason: "tool_use" 时取 content 中 tool_use 块；下一轮 user 消息回传 tool_result。

若渠道支持 prompt 缓存，可在块上加 "cache_control": {"type":"ephemeral"}；命中时 usage 会出现缓存相关字段。

6. Gemini 原生接口

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

# 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"]),  # 不要带 /v1beta
)
resp = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="为什么海水是咸的？",
)
print(resp.text)

图片输入：parts 中放 {"inlineData":{"mimeType":"image/png","data":"<base64>"}}。平台暂不支持 :countTokens（会 404），可参考响应里的 usageMetadata。

7. 推理 / Thinking

思考过程消耗 token（通常按输出计费），并占用 max_tokens。

Claude 原生：

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
开启后勿再设 temperature / top_k 等采样参数
也可直接用 claude-opus-4-6-thinking；Chat Completions 下思考多在 reasoning_content

Gemini： Chat Completions 可传 reasoning_effort；原生可用 generationConfig.thinkingConfig（如 thinkingBudget、includeThoughts，Gemini 3 系列还有 thinkingLevel）。

DeepSeek / Kimi / GLM / Qwen： 经 Chat Completions；若有思考过程，多在 reasoning_content。

常见坑：返回空内容且 finish_reason: length → max_tokens 太小，全被思考占满；参数报错 → 先删采样参数；首字慢 → 用流式。

8. SDK 速览

python

# OpenAI SDK — Chat Completions
from openai import OpenAI
client = OpenAI(api_key="sk-xxxxxxxx", base_url="https://ai.afp.net/v1")
print(client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "你好"}],
).choices[0].message.content)

python

# Anthropic SDK — 注意 base_url 不要带 /v1
import anthropic
claude = anthropic.Anthropic(api_key="sk-xxxxxxxx", base_url="https://ai.afp.net")
msg = claude.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)

python

# LangChain
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)

环境变量：

bash

export OPENAI_API_KEY="sk-xxxxxxxx"
export OPENAI_BASE_URL="https://ai.afp.net/v1"
export ANTHROPIC_API_KEY="sk-xxxxxxxx"
export ANTHROPIC_BASE_URL="https://ai.afp.net"

9. 错误与排障（摘要）

状态码	常见原因
400	JSON/参数错误；Claude 缺 `max_tokens`；模型不支持某参数
401	Key 错误、缺 `Bearer` 、令牌已删
403	余额/令牌额度不足、模型未授权、IP 白名单
404	Base URL 多/少 `/v1`，或路径不存在
429	限流 → 指数退避重试
502/503	上游或当前分组无可用渠道
504	超时 → 改流式或加大超时

排障顺序：最小 curl → GET /v1/models 核对模型名 → 去掉可选参数 → 查控制台「使用日志」。联系客服时提供时间（注明 Asia/Shanghai）、模型、路径、错误信息；不要发完整 Key。

更多错误码与令牌/分组说明见完整参考。

10. 本页 FAQ

新项目该用 /v1/chat/completions 还是 /v1/responses？
在词源探索优先 Chat Completions。确认模型支持且需要 Responses 特性时再用 Responses。

用 OpenAI SDK 能调 Claude / Gemini 吗？
可以，把 model 换成对应 ID。要用 Claude 缓存、Gemini 原生生图等独有能力时，改用原生协议。

图片参数怎么传？
Responses：input_image；Chat Completions：image_url；Anthropic：image + source；Gemini：inlineData。公网 URL 或 Data URL 均可。

为什么图片请求没效果？
确认模型支持视觉；URL 可公网访问（否则用 Data URL）；别把生图接口参数塞进对话接口。

为什么推理模型报参数不支持？
先删掉 temperature、top_p、presence_penalty、frequency_penalty、logprobs 等，再逐个加回。

为什么流式不能直接 JSON.parse？
那是 SSE 事件流，需按行读 data:，遇到 [DONE] 结束。

控制台有余额，API 却提示额度不足？
检查令牌自身的额度上限是否用尽；账户余额与令牌额度是两回事。

支持文件上传、微调、Assistants 吗？
不支持；/v1/files、/v1/fine-tunes 等可能返回 501。文档请提取为文本或按图片传入。

上一页：帮助中心 · 下一页：图像生成与编辑

大模型 API 接入指南 ​

1. 选择端点 ​

2. 查询模型 ​

当前模型一览（快照） ​

Claude ​

Gemini ​

其他文本模型 ​

3. OpenAI Chat Completions（推荐） ​

文本请求 ​

图片输入（看图，不是生图） ​

工具调用 ​

流式输出 ​

常用字段 ​

4. OpenAI Responses ​

5. Anthropic Messages ​

6. Gemini 原生接口 ​

7. 推理 / Thinking ​

8. SDK 速览 ​

9. 错误与排障（摘要） ​

10. 本页 FAQ ​

大模型 API 接入指南

1. 选择端点

2. 查询模型

当前模型一览（快照）

Claude

Gemini

其他文本模型

3. OpenAI Chat Completions（推荐）

文本请求

图片输入（看图，不是生图）

工具调用

流式输出

常用字段

4. OpenAI Responses

5. Anthropic Messages

6. Gemini 原生接口

7. 推理 / Thinking

8. SDK 速览

9. 错误与排障（摘要）

10. 本页 FAQ