接口约定
飞鱼Token 对外提供两套兼容接口：OpenAI 格式与 Anthropic 格式。改 base_url 与 API Key 就能用现有 SDK。
接入地址
两套协议用同一个域名，但 base_url 的写法不一样 —— 这一点最容易填错：
| 协议 | base_url | 完整路径 |
|---|---|---|
| OpenAI 格式 | https://open.feiyutoken.com/v1 |
https://open.feiyutoken.com/v1/chat/completions |
| Anthropic（Claude）格式 | https://open.feiyutoken.com |
https://open.feiyutoken.com/v1/messages |
Anthropic 系的 SDK 与工具会自己补 /v1/messages，所以 base_url 填到域名就够了；
填成带 /v1 的会变成 /v1/v1/messages。
鉴权
API Key 在控制台创建，可以给每个 Key 单独设有效期、额度上限与 IP 白名单。 两种协议带的头不一样，SDK 会自动处理，手写请求时要注意：
# OpenAI 格式
-H "Authorization: Bearer <你的飞鱼Token API Key>"
# Anthropic 格式
-H "x-api-key: <你的飞鱼Token API Key>"
-H "anthropic-version: 2023-06-01"
请求与响应
请求体是 JSON，响应体的结构与你用的协议完全一致 —— 用 OpenAI SDK 就得到 OpenAI 的返回结构，用 Anthropic SDK 就得到 Anthropic 的返回结构，现有解析代码不用改。
每次响应都会带用量字段，可以直接拿来对账：
| 协议 | 用量字段 |
|---|---|
| OpenAI 格式 | usage.prompt_tokens / usage.completion_tokens / usage.total_tokens |
| Anthropic 格式 | usage.input_tokens / usage.output_tokens |
流式输出
请求体里加 stream: true 即走 SSE 流式：响应按 SSE 协议逐块下发，客户端边收边处理。
流式响应默认不带用量，需要统计 Token 时在请求里加上：
{ "stream": true, "stream_options": { "include_usage": true } }
这样最后一个 chunk 会带上 usage。SSE 本身不支持断点续传，连接中断后重新发起请求，需要重新发起请求。
错误处理
错误响应沿用对应协议的格式（OpenAI 格式是 {"error": {"message": ..., "type": ...}}），
HTTP 状态码含义：
| 状态码 | 含义 | 怎么处理 |
|---|---|---|
| 401 / 403 | 鉴权失败：Key 不对、已删除或鉴权失败或没有该模型的访问权限 | 检查 Key 与 base_url |
| 429 | 触发限流（请求过于频繁） | 退避重试；确认余额 |
| 5xx | 服务端或网络问题 | 稍后重试；持续失败请联系客服 |
计费与用量
按实际用量计费，费用从账户余额扣减。计费单位与模型厂商官网一致：文本按 Token， 图像按张数或分辨率，语音按字符数或时长，视频按时长。控制台可以按模型、按 Key、按时间查看 调用记录、用量与消费明细，报表支持导出。
接口一览
按分类列全。没列在这里的接口，就是当前部署没有开放。
对话（Chat）
| 接口 | 方法 | 路径 |
|---|---|---|
| Chat Completions API | POST |
https://open.feiyutoken.com/v1/chat/completions |
| Claude Messages API | POST |
https://open.feiyutoken.com/v1/messages |
| Responses API | POST |
https://open.feiyutoken.com/v1/responses |
这几个功能怎么用，另有三篇指南：JSON Output（结构化输出）、 Tool Calls（工具调用）、多轮对话（拼上下文）。
模型列表
| 接口 | 方法 | 路径 |
|---|---|---|
| 模型列表 | GET |
https://open.feiyutoken.com/v1/models |
补全（Completions）
| 接口 | 方法 | 路径 |
|---|---|---|
| 创建补全 | POST |
https://open.feiyutoken.com/v1/completions |
图像（Images）
| 接口 | 方法 | 路径 |
|---|---|---|
| 生成图像 | POST |
https://open.feiyutoken.com/v1/images/generations |
| 编辑图像 | POST |
https://open.feiyutoken.com/v1/images/edits |
音频（Audio）
实时语音是 WebSocket 握手入口，其余三个都是普通 HTTP 请求。
| 接口 | 方法 | 路径 |
|---|---|---|
| 文本转语音 | POST |
https://open.feiyutoken.com/v1/audio/speech |
| 音频转录 | POST |
https://open.feiyutoken.com/v1/audio/transcriptions |
| 音频翻译 | POST |
https://open.feiyutoken.com/v1/audio/translations |
| 实时语音会话 | GET |
https://open.feiyutoken.com/v1/realtime |
视频（Videos）
视频是异步任务：先创建，再用状态接口轮询。
| 接口 | 方法 | 路径 |
|---|---|---|
| 创建视频生成任务 | POST |
https://open.feiyutoken.com/v1/video/generations |
| 获取视频生成任务状态 | GET |
https://open.feiyutoken.com/v1/video/generations/{task_id} |
其他接口
| 接口 | 方法 | 路径 |
|---|---|---|
| 创建嵌入 | POST |
https://open.feiyutoken.com/v1/embeddings |
| 文档重排序 | POST |
https://open.feiyutoken.com/v1/rerank |
| 内容审核 | POST |
https://open.feiyutoken.com/v1/moderations |