天庭 TIANTING
登录

{ DOCUMENTATION }

API 接入文档

从第一次调用，到接入你习惯的工具。

OPENAI BASE URLhttps://api.tianting.dev/v1
01

快速开始

准备账号、创建密钥，然后把 SDK 的请求地址换成天庭。

  1. 注册并登录

    打开 console.tianting.dev，用邮箱、GitHub 或 LinuxDo 登录。

  2. 创建 API Key

    在控制台生成密钥，按项目分别管理，并妥善保存。不要把密钥写进网页、公开仓库或分享给他人。

  3. 设置地址与模型

    将base_url设置为https://api.tianting.dev/v1，填写自己的密钥和模型名。

export TIANTING_API_KEY="替换为你的 API Key"

以下代码为接入示例，不会在页面内发送请求。模型权限、余额及接口能力请以控制台与实际返回为准。

02

OpenAI 兼容协议

已有 OpenAI SDK 项目可从替换地址与密钥开始。模型名可在模型页查看。

POSThttps://api.tianting.dev/v1/chat/completions

请求示例

curl https://api.tianting.dev/v1/chat/completions \
  -H "Authorization: Bearer $TIANTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "你好"}]
  }'

常用请求字段

字段类型说明
modelstring目标模型的完整名称。
messagesarray对话消息，包含 role 与 content。
streamboolean请求流式返回，需目标模型与通道支持。
max_tokensinteger输出长度限制；适用字段与范围因模型而异。
temperaturenumber采样设置；部分模型不接受此参数。

工具调用、结构化输出与推理参数不是所有模型都一致支持，迁移前请用目标模型测试。

03

流式输出

在支持流式的模型与通道上，设置stream=True，即可逐段读取内容。不要假设每个数据块都有正文。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TIANTING_API_KEY"],
    base_url="https://api.tianting.dev/v1",
)
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "写一首关于星空的诗"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
04

Anthropic 协议

使用 Anthropic SDK 时，基础地址不带/v1；SDK 会自动拼接 Messages 路径。以下为原生协议配置参考，请先确认自己的密钥与通道可用。

POSThttps://api.tianting.dev/v1/messages
import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["TIANTING_API_KEY"],
    base_url="https://api.tianting.dev",
)
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "你好"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

思考块、提示缓存与工具调用等高级字段由具体模型和通道决定。读取正文时按type == "text"筛选，避免混入其他内容块。

05

Codex CLI

以下为自定义供应商配置参考。Codex 使用 Responses 协议，不能仅凭聊天接口可用就判断它兼容；请先确认当前通道支持/v1/responses。

npm install -g @openai/codex

配置供应商

# ~/.codex/config.toml
model = "gpt-5.5"
model_provider = "tianting"

[model_providers.tianting]
name = "TIANTING"
base_url = "https://api.tianting.dev/v1"
env_key = "TIANTING_API_KEY"
wire_api = "responses"

在同一终端设置TIANTING_API_KEY后运行codex。如出现接口不支持，请使用已确认兼容的 SDK 或通道。

06

Claude Code

已安装 Claude Code 的用户，可通过环境变量配置网关地址。使用前请确认通道支持 Anthropic Messages 与工具调用。

# macOS / Linux，当前终端会话
export ANTHROPIC_BASE_URL="https://api.tianting.dev"
export ANTHROPIC_AUTH_TOKEN="$TIANTING_API_KEY"
claude --model claude-opus-5-5

示例只影响当前终端会话。若本机已有其他供应商的配置，请先检查现有环境变量，避免地址和密钥混用。

07

其他客户端

CC Switch

在支持自定义供应商的版本中新增「TIANTING」，填写天庭密钥。Claude Code 使用不带/v1的地址，Codex 使用带/v1的地址，并确认对应协议可用。

OpenCode

使用 OpenAI 兼容供应商配置，密钥从环境变量读取。配置文件位置与字段请以所安装版本为准。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tianting": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TIANTING",
      "options": {
        "baseURL": "https://api.tianting.dev/v1",
        "apiKey": "{env:TIANTING_API_KEY}"
      },
      "models": {
        "gpt-5.5": { "name": "gpt-5.5" }
      }
    }
  },
  "model": "tianting/gpt-5.5"
}

桌面聊天客户端

如果客户端支持自定义 OpenAI 兼容地址，填写https://api.tianting.dev/v1、API Key 与模型名。并非所有桌面客户端都支持第三方网关；请勿把 Claude Code 的配置直接当作 Claude 桌面端的配置。

08

常见问题

请求无法通过认证？+

检查密钥是否完整、是否启用，以及请求头是否匹配协议。OpenAI 使用 Authorization: Bearer，Anthropic 示例使用 x-api-key。

地址返回 404？+

检查 base_url 是否重复拼接 /v1，及所调用的路径是否被当前通道支持。OpenAI SDK 基础地址带 /v1；Anthropic SDK 示例不带。

模型不存在或没有权限？+

核对完整模型名，并查看控制台的可用模型与密钥权限。模型目录不代表每个密钥都有调用权限。

请求参数报错？+

先尝试仅带 model 与 messages 的最小请求，再逐一加入参数。Anthropic Messages 还需要 max_tokens。不同模型的采样与推理参数可能不同。

Windows 请求失败？+

优先使用上面的 PowerShell 示例，以 UTF-8 发送 JSON；不要直接粘贴 Bash 的单引号与反斜杠续行写法。

如何核对用量？+

查看控制台的用量记录与结算信息；流式响应不一定包含完整用量，不能把缺失的 usage 当作零消耗。

先用最小请求验证，再接入你的项目。

选择模型