调用说明

OpenAI 兼容 API：改 Base URL 与 Key 即可接入。路由与合规在平台侧完成，调用端无感选择厂商；响应头如实记录实际货源（对标中转站「统一入口 + 来源可追溯」）。

概览

OpenAI 兼容 Base URL（以 /v1 结尾，对齐 OpenAI SDK）

…/v1

把 OpenAI SDK 的 base_url / baseURL 指到这里即可（与 https://api.openai.com/v1 同形）。Portal 会将 /v1/* 转发到网关。

鉴权

Header Authorization: Bearer sk_live_…

示例中的占位符换成 Keys 页创建的密钥；勿把明文 Key 提交到仓库。 Keys

能力	LinkAI	说明
对话	POST /v1/chat/completions	OpenAI Chat Completions 兼容
文生图	POST /v1/images/generations	OpenAI Images；别名 POST /v1/images。
模型列表	GET /v1/models	含 modality / pricing / 合规标签
余额	GET /v1/credits	平台扩展
用量	GET /v1/activity	平台扩展
当前 Key	GET /v1/key	限额与用量快照

快速开始

与 OpenRouter / OpenAI 相同：先建 Key，再发一条 chat completions。推荐用官方 OpenAI SDK，仅改 base URL。

export LINKAI_API_KEY=$LINKAI_API_KEY

curl …/v1/chat/completions \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "linkai/deepseek-v4-pro",
    "messages": [{"role": "user", "content": "你好"}]
  }'

流式输出

设置 stream: true，响应为 SSE（text/event-stream）。集成翻车最常见是代理缓冲或未读到 data: [DONE]——可在在线调试打开 stream 核对。在线调试 →

curl …/v1/chat/completions \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "linkai/deepseek-v4-pro",
    "stream": true,
    "messages": [{"role": "user", "content": "用三句话介绍海南"}]
  }'

请求参数

字段	类型	说明
model	string	平台模型 ID；也可用 auto / linkai/auto
messages	array	OpenAI 消息列表；content 可为 string 或多模态 parts
stream	boolean	默认 false；true 时返回 SSE
temperature	number	采样温度（模型声明支持时透传）
max_tokens	number	最大生成 token；亦接受 max_completion_tokens
top_p	number	核采样
tools / tool_choice	array / string\|object	工具调用；仅 modality 支持 tools 的模型可过闸
reasoning	object	OpenRouter 风格：{ effort, enabled, exclude }；网关翻译为上游 thinking
reasoning_effort	string	简写 effort：none / low / high / max（medium→high）
include_reasoning	boolean	false 时仍可能计思考 token，但不回传 reasoning 正文
thinking	object	DeepSeek 原生开关：{ type: enabled\|disabled }；与 reasoning 二选一即可

模型是否接受某参数，以模型目录的 supported_parameters / modality 为准。模型

思考 / Reasoning

支持思考的模型（如 linkai/deepseek-v4-pro）可用统一 reasoning 参数开关；不必记各厂商私有字段。

打开：reasoning: { effort: "high" } 或 reasoning: { enabled: true }
关闭：reasoning: { effort: "none" } 或 thinking: { type: "disabled" }
响应中 content 为最终答案；reasoning 与 reasoning_content 为思考链别名（同级字段）

curl …/v1/chat/completions \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "linkai/deepseek-v4-pro",
    "messages": [{"role":"user","content":"9.11 和 9.8 哪个大？"}],
    "reasoning": {"effort": "high"}
  }'

多轮工具调用时，请把上一轮 assistant 的 reasoning_content 原样带回 messages，否则部分上游会 400。思考与最终答案共用 max_tokens：额度过低会 HTTP 200 但 content 为空（建议 ≥4096）。

多模态

看图（Vision）走 POST /v1/chat/completions：content 可为数组 text / image_url / input_audio / file。选用 modality 含 image→text 的模型。

作图（Seedream 等）走 POST /v1/images/generations（或 /v1/images），不要用 chat。选用 modality 为 text+image→image 的模型。

curl …/v1/images/generations \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "linkai/doubao-seedream-5.0-pro",
    "prompt": "一只水墨风格的白鹤立于礁石",
    "size": "2K"
  }'

{
  "model": "linkai/doubao-seed-vision",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "描述这张图"},
      {"type": "image_url", "image_url": {"url": "https://example.com/demo.png"}}
    ]
  }]
}

模型与 auto

列出可用模型：GET /v1/models。写死 model 时走该 SKU；写 auto 时由 Portal「路由」页的候选池 / 倾向 / 智能路由挑选。货源与路由

透明自选：请求指定 linkai/…，不经路由页
选择倾向：model: "auto" + 账号均衡 / 价格 / 延迟倾向
智能路由：开则忽略池子，全站按同一倾向选（默认关）

货源与路由

调用端不指定厂商；平台按份额与质量调度。需要软优先某货源时，可加 Header（失败自动切换，不硬锁）：

curl …/v1/chat/completions \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -H "X-LinkAI-Provider: deepseek" \
  -H "Content-Type: application/json" \
  -d '{"model":"linkai/deepseek-v4-pro","messages":[{"role":"user","content":"你好"}]}'

可选 X-LinkAI-Session 辅助会话粘性；X-LinkAI-Node-Id 指定出境节点（高级）。

响应头

Header	含义
X-LinkAI-Origin-Provider	实际命中的货源（来源透明）
X-LinkAI-Provider-Preferred-Hit	优先货源是否命中
X-LinkAI-Fallback	是否发生过 failover（1/0）
X-LinkAI-Exit-Gateway	出境口岸（如 hainan）
X-LinkAI-Resource-Group	命中的资源组
X-LinkAI-Auto-Model	auto 解析后的实际 model
X-LinkAI-Export-Control	出口管制拦截时的原因码

错误码

非流式错误为 JSON（OpenAI 风格 error.message / type / code）。常见码：

HTTP	code	场景
401	invalid_api_key	缺少或错误的 Bearer Key
402 / 403	insufficient_credits	余额不足（先充值再调用）
403	firewall_blocked	Token 防火墙拦截
403	export_sanction_hit	出口管制闸门
400	invalid_request	模型不支持该 modality / tools 等
429	rate_limit_exceeded	RPM / TPM 超限
502 / 504	upstream_*	上游失败（可能已自动 failover）

余额与限流

先充值再调用：无体验赠送额度；余额不足会拒请求。
Key 级 RPM / TPM：见 GET /v1/key 与 Keys 详情。
账户与充值、用量可在控制台对应页面查看。 Credits · Activity

调不通？到在线调试用同一把 Key 发一笔真请求核对。在线调试 →