Modelink

认证与请求

获取 API Key

在 Modelink 控制台创建或复制 API Key。创建前请确认账号已完成必要认证，并具备目标服务和模型的调用权限。

API Key 命名

创建密钥时建议填写清晰名称或备注，例如：

  • prod-customer-service
  • staging-agent-test
  • batch-doc-summary
  • team-a-research

良好的命名便于区分用途、业务场景、内部使用者和用量来源。

认证方式

API Key 用于识别调用方身份，应只在服务端安全保存，不应暴露在浏览器、移动端安装包或公开仓库中。接口文档目前声明以下认证方式：

认证方式请求头格式适用接口说明
Modelink BearerAuthorization: Bearer <api_key>OpenAI 兼容、文件、素材、OpenAI 风格图像/视频、批量任务等需认证接口通用方式；部分原生协议和 FAL 接口也兼容此方式。模型列表可匿名访问。
Anthropic 原生请求头X-Api-Key: <api_key>POST /v1/messages、POST /bypass/anthropic/v1/messagesAnthropic 官方格式，推荐用于 Messages 接口；也可改用 Bearer。
Google 原生请求头X-Goog-Api-Key: <api_key>POST /bypass/vertex/v1/models/{model}:{invokeFuncName}Vertex/Gemini 原生格式；也可改用 Bearer。
FAL 兼容 KeyAuthorization: Key <api_key>/queue/... 图像和视频异步接口FAL 官方格式；这些接口也兼容 Bearer。
管理接口 AK/SK 签名Authorization: Qiniu <AccessKey>:<EncodedSign>POST /v1/apikeys；请求日志接口支持此方式或 Bearer使用 AK/SK 对请求做 HMAC-SHA1；普通 Modelink API Key 不能替代 AK/SK。
火山 V4 HMAC-SHA256 签名Authorization: HMAC-SHA256 Credential=..., SignedHeaders=..., Signature=...POST /volcengine/assets/?Action=...使用同一个 Modelink API Key 作为 Access Key 和签名密钥，并携带签名辅助请求头。

同一个请求只需使用该接口文档列出的其中一种认证方式。文档同时列出多个方式时表示“任选其一”，不需要同时发送多个 Authorization 或 API Key 请求头。<api_key> 均指 Modelink 控制台中的 API Key；OpenAPI 中的 bearerFormat 不要求该值必须是 JWT。

通用 Bearer

大多数接口使用 Bearer 认证：

Authorization: Bearer <api_key>

这包括 OpenAI Chat Completions、OpenAI Responses、文件、普通素材、OpenAI 风格图像/视频和批量推理接口。火山素材的项目查询接口 GET /v1/asset-projects 也使用 Bearer。模型列表 GET /v1/models 可不带认证；如果携带 API Key，则使用此 Bearer 格式。

Anthropic Messages

Anthropic 兼容接口和 Anthropic 原厂协议 Bypass 接口推荐使用 Anthropic 官方请求头：

X-Api-Key: <api_key>

适用路径为 POST /v1/messages 和 POST /bypass/anthropic/v1/messages。这两个接口也接受：

Authorization: Bearer <api_key>

Vertex / Gemini 原生协议

Vertex/Gemini 原生协议 Bypass 接口推荐使用 Google 官方请求头：

X-Goog-Api-Key: <api_key>

该方式仅对应 POST /bypass/vertex/v1/models/{model}:{invokeFuncName}。接口也接受 Bearer：

Authorization: Bearer <api_key>

这里的值仍是 Modelink API Key，不是 Google Cloud 服务账号 JSON 或 Google 项目密钥。

FAL 格式图像与视频接口

FAL 兼容的异步创建和任务查询接口使用 FAL 官方格式：

Authorization: Key <api_key>

这些接口位于图像和视频 OpenAPI 文档的 /queue/... 路径下，也接受通用 Bearer。使用 FAL SDK 或希望保持 FAL 客户端配置不变时，优先使用 Key 前缀。Webhook 的创建示例见 FAL 格式 Webhook。

管理接口 AK/SK 签名

管理接口中的批量创建 API Key 使用 Access Key（AK）和 Secret Key（SK）签名，而不是普通 Modelink API Key：

Authorization: Qiniu <AccessKey>:<EncodedSign>

EncodedSign 是使用 SK 对规范化请求计算 HMAC-SHA1 后得到的 URL-safe Base64 字符串。POST /v1/apikeys 必须使用该签名；GET /v2/stat/export_log 和 GET /v2/stat/export_log_file 可使用该签名或 Bearer。签名的规范化顺序、请求体要求和 Node.js/Python 示例见 AK/SK 请求签名。

火山素材 V4 签名

火山素材兼容接口采用两步认证，不能把两个步骤都写成 Bearer：

  1. 使用 Bearer API Key 调用 GET /v1/asset-projects，取得后续请求必须使用的 ProjectName。
  2. 对 POST /volcengine/assets/?Action=<Action>&Version=2024-01-01 生成火山 V4 HMAC-SHA256 签名。将同一个 Modelink API Key 同时作为 Credential 中的 Access Key 和签名密钥。

Action 请求必须同时发送以下请求头：

Authorization: HMAC-SHA256 Credential=<api_key>/<yyyyMMdd>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<hex_signature>
X-Date: <UTC yyyyMMdd'T'HHmmss'Z'>
X-Content-Sha256: <final_request_body_sha256>
Content-Type: application/json

X-Date 与服务端时间偏差不能超过 5 分钟。X-Content-Sha256 必须是最终请求体原始字节的 SHA-256 小写十六进制值；签名后不要重新序列化请求体。完整流程和请求示例见 火山协议 · 虚拟人像素材管理 和火山素材兼容接口。

环境变量配置

本地开发和服务端部署建议统一使用环境变量。OpenAI 兼容客户端的 Base URL 通常包含 /v1；Anthropic、FAL 和火山素材接口按各自路径拼接。

export MODELINK_API_KEY="替换为你的 Modelink API Key"
export MODELINK_BASE_URL="https://api.qnaigc.com/v1"
export MODELINK_MODEL="控制台中的模型 ID"

Node.js 服务端可这样初始化兼容客户端：

import OpenAI from "openai";

export const modelink = new OpenAI({
  apiKey: process.env.MODELINK_API_KEY,
  baseURL: process.env.MODELINK_BASE_URL ?? "https://api.qnaigc.com/v1",
});

信息

OpenAI 兼容 SDK 通常使用带 /v1 的 Base URL；Anthropic 兼容工具通常使用不带 /v1 的 Base URL，例如 https://api.qnaigc.com 或 https://api.modelink.ai。FAL 和火山素材接口请以对应 API Reference 中的完整路径为准。

用量追踪

建议按 API Key、环境、业务线和租户维度记录用量，重点关注：

  • 输入与输出 token
  • 模型名称
  • 请求成功率和错误率
  • 平均耗时和超时次数
  • 异常增长或疑似泄露调用

Modelink 控制台通常会提供按时间范围、API Key、模型和响应状态筛选的用量与请求日志能力。排查问题时，优先记录请求 ID、请求时间、模型、状态码和错误信息；若本地未保存请求 ID，可在控制台请求日志中按时间、API Key、模型或响应状态反查。

安全要求

警告

不要在日志、错误上报、前端页面、移动端包、公开仓库或截图中暴露完整密钥。

  • 使用环境变量或密钥管理服务保存 API Key。
  • 不同环境使用不同密钥。
  • 定期轮换生产密钥。
  • 一旦泄露，立即禁用旧密钥并检查调用记录。
  • 管理接口的 SK 和火山 V4 签名所用密钥只能在服务端使用；不要把签名结果、规范化请求字符串或签名辅助请求头写入公开日志。

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify