跳到正文
土土金API

开始

认证与 Base URL

所有接口都用控制台创建的 sk- 开头的 Key 认证。OpenAI 格式用 Authorization 请求头,Claude 原生也认 x-api-key,Gemini 原生也认 x-goog-api-key;OpenAI 兼容 Base URL 是 https://www.tutujin.com/v1。

所有接口都用同一把 API Key 认证,Key 在控制台创建,以 sk- 开头。OpenAI 格式的请求把 Key 放在 Authorization: Bearer 请求头里;Claude 原生和 Gemini 原生接口还认各自官方 SDK 默认使用的请求头,所以用官方 SDK 时只要改 base URL 和 Key。

三种请求头写法

接口格式请求头生效范围
OpenAI 兼容(Chat Completions、Responses、Embeddings、图像、语音、Rerank)Authorization: Bearer sk-...所有接口
Claude 原生 Messagesx-api-key: sk-...,同时带 anthropic-version: 2023-06-01/v1/messages 和模型列表接口
Gemini 原生 generateContentx-goog-api-key: sk-.../v1beta/models/... 和模型列表接口

Authorization: Bearer 在任何接口上都能用,包括 Claude 和 Gemini 的原生路径。另外两种写法是为了兼容官方 SDK,不需要自己改请求头。Gemini 原生路径也接受 URL 参数 ?key=,但 URL 容易被日志和代理记录下来,建议用请求头。

curl https://www.tutujin.com/v1/chat/completions \
  -H "Authorization: Bearer $TUTUJIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "你好"}]
  }'

Base URL 怎么填

OpenAI SDK 的 base URL 要带 /v1;Anthropic 和 Google 的 SDK 会自己在后面拼接口路径,所以只填站点根地址。

你在用的 SDK 或方式参数填写的值
OpenAI SDK(Python / Node.js)base_url / baseURL,或环境变量 OPENAI_BASE_URLhttps://www.tutujin.com/v1
Anthropic SDKbase_url / baseURLhttps://www.tutujin.com
Google Gen AI SDKhttp_options 里的 base_urlhttps://www.tutujin.com
直接发 HTTP 请求完整地址例如 https://www.tutujin.com/v1/chat/completions、https://www.tutujin.com/v1/messages
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.tutujin.com/v1",
    api_key=os.environ["TUTUJIN_API_KEY"],
)

各个 SDK 的完整用法见 OpenAI SDK、Anthropic SDK 两篇集成指南。

Key 的权限设置

在控制台新建或编辑 Key 时,可以给每把 Key 单独限定:

设置不满足时的结果
分组决定这把 Key 走哪条线路、按哪档价格计费,见选择分组
额度上限这把 Key 花完上限后返回 401,其他 Key 不受影响
过期时间过期后返回 401
模型白名单调用白名单以外的模型返回 403
IP 白名单来自其他 IP 的请求返回 403

控制台默认只显示 Key 的掩码。建议一个项目、一个环境各用一把 Key,生产环境的 Key 设上模型白名单和 IP 白名单,泄露后能把损失限制在一把 Key 内。更多做法见 API Key 安全最佳实践。

Key 只能放在服务器端,用环境变量或密钥管理服务保存。不要写进网页、App、小程序的前端代码,也不要提交到代码仓库。

认证相关的报错

状态码常见原因怎么处理
401Key 填错、已删除、已禁用、已过期,或这把 Key 的额度上限用完了检查请求头里的 Key 是否完整,在控制台确认 Key 的状态
403账户余额不足、IP 不在白名单、模型不在白名单、Key 的分组不可用按报错信息调整设置或充值,不要自动重试

完整的状态码说明和重试建议见错误码与重试。

没找到答案?加客服微信 JsnonoChat,发送报错信息里的 request id,我们帮你排查。