接口与协议

QiyuanHub 是推理端点，不绑定某一家 SDK：你的客户端习惯发哪种协议，就发哪种，鉴权与计费完全一样。Base URL 统一为下面这个地址，OpenAI 风格客户端务必带 /v1，Anthropic 风格客户端的 ANTHROPIC_BASE_URL 也填它。

• 模型名统一填 deepseek-v4.1；完整清单以控制台「模型」页和 GET /v1/models 为准
• 三种协议都支持流式输出、系统提示词、函数工具调用、思考强度设置与 100 万 token 上下文
• 目前开放对话类接口与图像生成接口（POST /v1/images/generations，模型 seedream-5.0-pro，见「常见问题」）。Embedding、语音等接口尚未开放，请勿照 SDK 默认示例调用

Base URL：https://api.qiyuanapi.cc/v1
鉴权：Authorization: Bearer sk-opc-your-api-key

POST /v1/chat/completions   OpenAI Chat Completions —— 通用，绝大多数 SDK / 客户端的默认协议
POST /v1/responses          OpenAI Responses —— Codex、OpenAI Agents SDK 等新一代客户端
POST /v1/messages           Anthropic Messages —— Claude Code、Claude Agent SDK 等
GET  /v1/models             当前 Key 可用的模型清单

标准的 /v1/chat/completions，任何兼容 OpenAI 的 SDK 只需替换 baseURL 与 apiKey。

• stream: true —— 标准 SSE 流式，最后一个块带 usage
• tools / tool_choice —— OpenAI function 工具；模型返回 tool_calls，你把结果以 role=tool 消息回传即可
• response_format: {"type": "json_schema"} —— 结构化输出，按 schema 约束生成
• 图片输入 —— content 里放 image_url 部件，用法见「图片理解」
• reasoning_effort —— none / low / high / xhigh，不传即模型默认 high，见「思考强度设置」
• 对话中途插入 system 消息也可以，平台会按模型模板处理

curl https://api.qiyuanapi.cc/v1/chat/completions \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    "stream": true
  }'

Codex、OpenAI Agents SDK 以及新版 OpenAI SDK 的 client.responses.* 走的都是这个协议。平台原生提供 /v1/responses，不是把它翻译成旧接口，所以多轮续链、工具回执这些 Responses 特有的语义都在。

• stream: true —— 标准 Responses 事件流（response.output_text.delta 等）
• 多轮续链 —— 返回的 id 可作为下一轮的 previous_response_id，只需发送新增内容。服务端在内存里短期保留最近的回复用于续链，不落盘；平台例行维护重启后旧 id 会找不到（404），客户端把完整输入重发一次即可，Codex 会自动回退
• 工具 —— tools 里的 function 工具，模型输出 function_call，你回传 function_call_output；Codex 用的 custom 工具与 custom_tool_call_output 平台也会自动转换
• 输入部件 —— message 里的 input_text / output_text 都接受；instructions 等价于 system 提示词
• reasoning: {"effort": ...} —— 档位与 Chat Completions 一致，见「思考强度设置」
• max_output_tokens 要给够 —— 思考与正文共用这个额度，给 200 会拿到空正文，建议 800 以上或不传
• 不支持 web_search、code_interpreter、file_search 这类由服务端执行的内置工具，原因见「联网搜索」

# 第一轮
curl https://api.qiyuanapi.cc/v1/responses \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1",
    "instructions": "你是一个严谨的代码助手",
    "input": "帮我解释一下这段报错：TypeError: x is not a function",
    "reasoning": {"effort": "low"},
    "store": true
  }'

# 第二轮：只发新增内容，上一轮通过 previous_response_id 接上
curl https://api.qiyuanapi.cc/v1/responses \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1",
    "previous_response_id": "resp_上一轮返回的id",
    "input": "那我该怎么改？"
  }'

Claude Code、Claude Agent SDK 等 Anthropic 风格客户端把 ANTHROPIC_BASE_URL 指向本站即可，平台在服务端完成协议转换，客户端无感。有的客户端配置界面把「OpenAI 地址」与「Anthropic 地址」分开填：Anthropic 地址填 https://api.qiyuanapi.cc/anthropic 也可以（客户端会自动补 /v1/messages），与直接填本站地址完全等价。

• 鉴权用 ANTHROPIC_AUTH_TOKEN（Bearer 头），不要设 ANTHROPIC_API_KEY，两者同时存在时客户端会优先走后者而失败
• stream: true —— 标准 Anthropic 事件流
• tools —— Anthropic 的 tool_use / tool_result 工具调用循环可用；原生 web_search 工具不可用（400），见「联网搜索」
• thinking —— 用 thinking.budget_tokens 控制思考深浅，平台会翻译成对应档位；思考内容不会以 thinking 块返回
• 模型名填 deepseek-v4.1；客户端自带的 claude-* 模型名会返回 404，Claude Code 的模型改法见「Claude Code 配置」

curl https://api.qiyuanapi.cc/v1/messages \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1",
    "max_tokens": 4096,
    "system": "你是一个严谨的代码助手",
    "messages": [{"role": "user", "content": "帮我解释一下这段报错：TypeError: x is not a function"}]
  }'

• 限流、并发与每分钟 token 额度按账户档位生效，触发时返回 429 并附 Retry-After，请按它退避重试，不要立刻重发
• 401 Key 无效 / 402 余额不足 / 403 未审核或 IP 不在白名单 / 404 模型名不存在，含义在各协议下一致
• 命中缓存的输入按缓存价计费，三种协议的用量字段都会给出命中数；缓存靠前缀完全一致来命中，多轮对话请追加而不要改写历史
• 单次请求输入上限为 100 万 token；其中未命中缓存、需要新计算的部分按账户档位另有单次上限（C 档 51.2 万 / B 档 76.8 万 / V 档 100 万），续写同一会话时已缓存的部分不计。超出返回 400，错误码 context_length_exceeded，带自动压缩能力的客户端会自动精简后重发