接入文档 · PivotX

01 · PREPARE

创建并保存 API Key

登录控制台创建独立密钥。建议不同项目使用不同密钥，发生泄露时可以单独撤销，不影响其他业务。

API Base URLhttps://api.pivotx.top

首次接入请先使用小额余额测试。模型标识、可用状态和实时价格以控制台显示为准。

02 · ENDPOINTS

选择兼容端点

根据现有 SDK 和模型类型选择端点。不要把完整请求地址重复拼接两个 /v1。

/v1/chat/completionsOpenAI 兼容对话请求

/v1/messagesAnthropic Messages 兼容请求

/v1/models使用有效密钥查询开放模型

03 · CURL

发送第一条请求

以下示例使用 Messages 兼容格式。将模型标识替换为控制台中实际开放的名称。

Terminal

curl https://api.pivotx.top/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

04 · PYTHON

OpenAI Python SDK

先执行 pip install openai，再通过环境变量读取密钥。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PIVOTX_API_KEY"],
    base_url="https://api.pivotx.top/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "Hello"}],
)

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

05 · NODE.JS

OpenAI Node.js SDK

先执行 npm install openai。密钥应由服务端环境变量提供，不能写入浏览器代码。

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PIVOTX_API_KEY,
  baseURL: "https://api.pivotx.top/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "Hello" }],
});

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

06 · ERRORS

处理常见错误

400检查请求格式、模型标识和必要参数。

401检查 API Key 是否正确、有效或已被撤销。

429降低请求频率，并采用带抖动的指数退避。

5xx记录请求时间与错误信息，有限重试后执行降级。

生产环境应设置连接和响应超时。不要无限重试，也不要在日志中记录完整 API Key 或敏感提示词。

07 · SECURITY

上线前的安全清单

仅在服务端保存 API Key，并通过环境变量读取。
按项目拆分密钥，设置合理的并发和额度限制。
为请求设置超时、有限重试、降级模型和错误告警。
定期查看消费明细，发现异常后立即撤销相关密钥。

从 API Key 到第一条请求