TniayApi 接口文档

文档说明

本文档为TniayApi的OpenAI标准API接入指南，接口完全遵循OpenAI API协议规范，支持现有基于OpenAI API开发的应用无缝对接，无需修改核心业务代码，仅需调整请求地址及鉴权配置即可完成接入。

一、接入准备

1.1 基础信息

• API根地址：https://api.134506.xyz/
• 协议支持：HTTPS
• 请求方式：POST（部分查询接口为GET）
• 数据格式：请求/响应均为JSON格式
• 字符编码：UTF-8

1.2 鉴权方式

采用OpenAI标准API Key鉴权，请求头中携带API Key完成身份验证，获取API Key后请妥善保管，避免泄露。

• 鉴权请求头字段：Authorization
• 字段值格式：Bearer {your_api_key}（{your_api_key}替换为实际获取的API Key）

二、通用请求规范

2.1 公共请求头

所有接口请求均需携带以下公共请求头，缺失将导致请求失败：

2.2 通用响应格式

接口响应统一返回JSON格式，包含状态码、提示信息、数据体三部分，与OpenAI标准响应结构一致。

成功响应

{
  "id": "chatcmpl-xxxxxx",
  "object": "chat.completion",
  "created": 1718987654,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "响应内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

失败响应

{
  "error": {
    "message": "Invalid API Key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

2.3 常见错误码

三、核心接口接入示例

以下为最常用的聊天补全接口接入示例，其他接口（如文本补全、embeddings、图片生成等）均遵循OpenAI标准参数规范，直接使用https://api.134506.xyz/作为根地址即可。

3.1 聊天补全接口（Chat Completions）

接口信息

• 接口路径：/v1/chat/completions
• 请求方式：POST
• 支持模型：以模型广场为准

请求参数

非流式请求示例（curl）

curl https://api.134506.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your_api_key}" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "system", "content": "你是一个智能助手"},
      {"role": "user", "content": "介绍一下OpenAI API的特点"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

流式请求示例（curl）

流式返回需设置stream: true，服务端会以SSE（服务器发送事件）形式逐段返回数据：

curl https://api.134506.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your_api_key}" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "用一句话描述人工智能"}],
    "stream": true
  }'

3.2 Embeddings向量生成接口

接口信息

• 接口路径：/v1/embeddings
• 请求方式：POST
• 支持模型：以模型广场为准

极简请求示例

curl https://api.134506.xyz/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your_api_key}" \
  -d '{
    "input": "需要生成向量的文本内容",
    "model": "text-embedding-ada-002"
  }'

四、开发语言对接示例

4.1 Python对接（使用openai官方库）

OpenAI Python官方库支持自定义API根地址，无需修改库源码，仅需初始化时配置base_url即可：

步骤1：安装依赖

pip install openai>=1.0.0

步骤2：代码示例

from openai import OpenAI

# 初始化客户端，配置自定义API根地址和API Key
client = OpenAI(
    api_key="{your_api_key}",  # 替换为实际API Key
    base_url="https://api.134506.xyz/v1"
)

# 调用聊天补全接口
response = client.chat.completions.create(
    model="gpt-3.5-turbo",  # 模型名称以模型广场为准
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

# 打印响应结果
print(response.choices[0].message.content)

4.2 Java对接（使用okhttp）

import okhttp3.*;
import com.alibaba.fastjson2.JSONObject;
import java.io.IOException;

public class TniayAIClient {
    private static final String API_KEY = "{your_api_key}"; // 替换为实际API Key
    private static final String BASE_URL = "https://api.134506.xyz/v1/chat/completions";
    private static final OkHttpClient client = new OkHttpClient();

    public static void main(String[] args) {
        // 构造请求体
        JSONObject requestBody = new JSONObject();
        requestBody.put("model", "gpt-3.5-turbo"); // 模型名称以模型广场为准
        JSONObject message = new JSONObject();
        message.put("role", "user");
        message.put("content", "Hello!");
        requestBody.put("messages", new JSONObject[]{message});

        // 构造请求
        Request request = new Request.Builder()
                .url(BASE_URL)
                .addHeader("Authorization", "Bearer " + API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(MediaType.parse("application/json"), requestBody.toJSONString()))
                .build();

        // 发送请求并处理响应
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful()) {
                System.out.println(response.body().string());
            } else {
                System.out.println("请求失败：" + response.code());
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

五、限流与配额说明

1. 接口限流遵循OpenAI标准限流规则，不同模型/API Key拥有不同的每秒请求数（RPS）和每日token配额，具体以实际开通权限为准；
2. 当触发限流时，服务端将返回429错误，建议客户端实现退避重试机制（如指数退避），避免频繁请求加剧限流；
3. 可通过查询接口获取当前API Key的配额使用情况（接口路径：/v1/usage，GET方式）。

六、注意事项

1. 所有接口请求的JSON参数需保证格式合法，避免存在多余逗号、引号未闭合等语法错误，否则将返回400错误；
2. 流式返回接口（stream: true）需客户端支持SSE解析，处理完成后需及时关闭连接，避免资源泄漏；
3. API Key若不慎泄露，需立即联系管理员重置，防止被恶意使用；
4. 建议客户端对请求进行超时设置（推荐30秒），避免因网络问题导致请求挂起；
5. 模型名称请以模型广场为准，如需使用图片生成（DALL-E）、语音转文字（Whisper）等接口，仅需将请求路径替换为OpenAI标准路径（如/v1/images/generations），请求参数与OpenAI官方文档完全一致。

七、技术支持

若接入过程中遇到问题，可通过以下方式获取技术支持：

1. 核对请求地址、API Key、参数格式是否符合本文档规范；
2. 查看接口返回的错误信息，根据错误码排查问题；
3. 联系平台管理员，提供请求ID、请求参数、错误信息，协助定位问题。

附录：OpenAI标准接口路径参考

本接口完全兼容OpenAI官方API文档的所有参数及响应规范，未在本文档中详细说明的接口/参数，请参考OpenAI官方API文档：https://platform.openai.com/docs/api-reference/introduction。