API 快速接入

本页用于帮助开发者快速完成第一次 API 调用。应天AI 提供 OpenAI 兼容的接口格式，已经在使用 OpenAI SDK、HTTP 客户端或自动化脚本的项目，通常只需要替换 Base URL、Token 和模型名称即可开始联调。

如果你还没有创建 Token，请先阅读客户新手使用指南和 API Key 管理。

接入前准备

开始调用前，请确认已经准备好以下信息：

配置项	用途	示例
Base URL	SDK 或 HTTP 请求使用的接口根地址	`https://ai.t1qq.com/v1`
API Token	请求身份认证凭证	`sk-...`
Model	要调用的模型标识	`gpt-4o`

模型名称、可用额度、上下文长度和具体参数能力可能随账号或平台配置变化。示例中的 gpt-4o 仅用于展示格式，实际调用时请以控制台显示的可用模型为准。

接口地址

API 地址：

text

https://ai.t1qq.com/v1

常用接口如下：

用途	方法	请求地址
查询模型	`GET`	`https://ai.t1qq.com/v1/models`
对话补全	`POST`	`https://ai.t1qq.com/v1/chat/completions`

在 OpenAI SDK 中，应将 https://ai.t1qq.com/v1 作为 base_url 或 baseURL 传入，不要再额外拼接一次 /v1。

认证与密钥安全

所有 API 请求都需要使用 Bearer Token 认证：

http

Authorization: Bearer 你的Token
Content-Type: application/json

请注意以下事项：

Token 应在控制台创建、查看和管理。
不要把真实 Token 提交到 Git 仓库、写入前端代码或发布到公开文档。
生产环境建议通过环境变量或密钥管理服务注入 Token。
分享请求日志、报错截图或代码片段前，请先遮盖 Token。

例如，在 PowerShell 中可以临时设置环境变量：

powershell

$env:AI_API_KEY = "你的Token"

第一次调用：先查询模型

如果不确定模型名称，可以先请求模型列表。该请求能够同时验证 Base URL 和 Token 是否基本可用：

bash

curl https://ai.t1qq.com/v1/models \
  -H "Authorization: Bearer 你的Token"

从返回结果中找到控制台允许当前 Token 使用的模型标识，再填入后续请求的 model 字段。若模型列表接口不可用，则直接以控制台显示的模型名称进行最小调用，并根据返回错误排查权限或路径问题。

最小请求：Chat Completions

确认模型后，先发送不带复杂参数的请求：

bash

curl https://ai.t1qq.com/v1/chat/completions \
  -H "Authorization: Bearer 你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "请只回复：API 接入成功"
      }
    ]
  }'

请求体中的关键字段：

字段	类型	说明
`model`	string	控制台中可用的模型名称。
`messages`	array	对话消息数组，至少包含一条 `user` 消息。
`messages[].role`	string	常用值为 `system`、`user` 和 `assistant`。
`messages[].content`	string	当前消息的文本内容。
`stream`	boolean	是否启用流式输出；不传时按普通响应处理。

成功时，响应中通常可以在 choices[0].message.content 看到模型内容，同时可根据返回信息查看模型和用量等数据。

流式输出

需要边生成边展示内容时，可以将 stream 设置为 true：

bash

curl -N https://ai.t1qq.com/v1/chat/completions \
  -H "Authorization: Bearer 你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍 API 接入流程"
      }
    ]
  }'

流式响应通常是 SSE（Server-Sent Events）格式，每个事件以 data: 开头，完成时会收到结束标记。使用命令行测试时建议保留 curl -N，避免终端缓冲导致内容集中显示。客户端不能把流式响应当作单个 JSON 一次性解析，应逐段读取并拼接内容。

如果你的业务不需要实时显示，建议先使用普通响应完成联调，确认认证、模型和参数都正确后再启用流式输出。

Python 接入示例

先安装 OpenAI Python SDK：

bash

pip install openai

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url="https://ai.t1qq.com/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "请只回复：Python 接入成功"}
    ],
)

print(response.choices[0].message.content)

如果暂时不使用环境变量，也可以直接传入 Token，但不要将包含真实密钥的文件提交到公共仓库。

Node.js 接入示例

先安装 OpenAI Node.js SDK：

bash

npm install openai

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AI_API_KEY,
  baseURL: "https://ai.t1qq.com/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "请只回复：Node.js 接入成功" },
  ],
});

console.log(response.choices[0].message.content);

如何确认调用成功

可以从以下几个方面判断接入是否完成：

HTTP 状态码正常，没有出现 401、403 或 404。
返回结果中包含模型生成的文本内容。
控制台日志中能找到对应的请求记录。
请求使用的模型、状态和消耗信息符合预期。
使用流式请求时，客户端能正确读取事件并识别结束标记。

建议按照“模型查询（可选）→ 普通最小请求 → SDK 调用 → 流式输出 → 接入业务”的顺序验证。每次只增加一项复杂度，便于定位问题。

常见错误与排查方法

401 Unauthorized

通常表示 Token 缺失、无效或格式不正确，请检查：

是否使用了最新且未过期的 Token；
请求头是否为 Authorization: Bearer 你的Token；
Token 前后是否混入空格、换行或引号；
SDK 是否同时配置了错误的环境变量，覆盖了预期 Token。

403 Forbidden

通常表示当前 Token 或账号没有访问所选模型的权限，请检查模型是否对当前账号开放，以及 Token 是否配置了模型限制、IP 白名单或其他访问策略。

404 Not Found

通常表示 Base URL 或接口路径不正确，请检查：

Base URL 是否为 https://ai.t1qq.com/v1；
SDK 是否自动拼接路径，导致 /v1 被重复添加；
是否误把 https://ai.t1qq.com/ 这样的站点地址直接当成 API Base URL；
请求方法和端点是否匹配。

模型不存在或参数不支持

请以控制台实际可用模型为准，不要直接照抄示例模型。部分模型对上下文长度、工具调用、图像输入或流式输出的支持不同，建议先删除非必要参数，再逐项恢复。

429 或请求频率受限

这通常表示触发了并发数、频率或额度限制。可以检查控制台中的额度和用量，在业务侧控制并发、适当重试，并避免无间隔地重复发送相同请求。

客户端有返回，但控制台没有日志

通常说明请求没有到达平台。请检查实际发出的 URL、代理配置、网络连通性，以及是否调用了另一个环境或服务地址。

流式响应解析失败

流式请求返回的是事件流，不是一次性 JSON。请确认请求设置了 "stream": true 后，客户端使用 SSE 方式逐条读取；如果只需要最终结果，则去掉该参数或设置为 false。

接入其他工具

在 Cursor、Cherry Studio、ChatBox 或其他支持 OpenAI 兼容格式的客户端中，通常填写：

API Key / Token：控制台创建的 Token；
Base URL：https://ai.t1qq.com/v1；
Model：控制台中实际可用的模型名称。

如果客户端要求填写“API 地址”而不是“Base URL”，请确认它最终请求的是 /v1/chat/completions，不要重复填写完整路径导致客户端再次拼接。

下一步

完成最小调用后，可以继续：

阅读客户新手使用指南；
查看 API Key 管理；
查看模型与价格；
返回新手指引；
将同一套 Base URL、Token 和模型配置接入正式业务。

API 快速接入 ​

接入前准备 ​

接口地址 ​

认证与密钥安全 ​

第一次调用：先查询模型 ​

最小请求：Chat Completions ​

流式输出 ​

Python 接入示例 ​

Node.js 接入示例 ​

如何确认调用成功 ​

常见错误与排查方法 ​

401 Unauthorized ​

403 Forbidden ​

404 Not Found ​

模型不存在或参数不支持 ​

429 或请求频率受限 ​

客户端有返回，但控制台没有日志 ​

流式响应解析失败 ​

接入其他工具 ​

下一步 ​

API 快速接入

接入前准备

接口地址

认证与密钥安全

第一次调用：先查询模型

最小请求：Chat Completions

流式输出

Python 接入示例

Node.js 接入示例

如何确认调用成功

常见错误与排查方法

401 Unauthorized

403 Forbidden

404 Not Found

模型不存在或参数不支持

429 或请求频率受限

客户端有返回，但控制台没有日志

流式响应解析失败

接入其他工具

下一步