API 文档

开发者优先：从快速开始到计费、错误码与排障。

快速开始

注册登录后，在控制台创建 API Key，然后即可发起第一次请求。

大多数工具可直接使用 OpenAI 兼容接口：配置 base URL 与 API Key 即可调用。

本文档中使用的示例域名为 https://api.example.com，请替换为你控制台里展示的实际地址。

环境变量（bash / zsh）

export BASE_URL="https://api.example.com/v1"
export API_KEY="your_api_key"

curl — 第一次请求

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.2","messages":[{"role":"user","content":"Hello"}]}'

Base URL 与 API Key

Base URL 通常形如：https://api.example.com/v1。你可以在控制台查看并复制。

API Key 用于标识调用方与权限范围，请妥善保管，不要在浏览器端代码中明文暴露。

如果你在团队内使用，建议为不同项目/环境创建不同 Key，并通过分组与预算限制进行隔离。

环境变量（PowerShell）

$env:BASE_URL = "https://api.example.com/v1"
$env:API_KEY = "your_api_key"

鉴权

通过 Authorization Header 以 Bearer token 方式传递 API Key：Authorization: Bearer <API_KEY>。

推荐做法：按项目拆分 Key，开启 IP 白名单，并配置可选预算/到期时间（便于风控与审计）。

如需重试，建议在客户端侧实现指数退避（exponential backoff），并尽量避免并发风暴。

OpenAI 兼容接口

可使用标准 OpenAI SDK，通过自定义 base URL 接入。

可支持 Chat Completions、Images 等（取决于你启用的模型与权限）。

如你已有 OpenAI 生态的工具链，通常只需要替换 base URL 与 API Key。

Node.js（OpenAI SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: process.env.BASE_URL
});

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

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

Python（OpenAI SDK）

from openai import OpenAI
import os

client = OpenAI(
  api_key=os.environ.get("API_KEY"),
  base_url=os.environ.get("BASE_URL")
)

res = client.chat.completions.create(
  model="gpt-5.2",
  messages=[{"role": "user", "content": "Hello"}]
)

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

聊天

端点：POST /v1/chat/completions。

核心参数：model、messages；常用可选参数：temperature、max_tokens、stream。

messages 为对话数组，每条包含 role（system/user/assistant）与 content。

API 说明

https://api.example.com/v1/chat/completions

OpenAI 兼容的聊天生成接口，请求体字段按常见 Chat Completions 规范整理。

请求方法

POST

接口地址

https://api.example.com/v1/chat/completions

请求参数

请求头

参数	类型	是否必填	说明
Authorization	string	必填	Bearer 鉴权头，格式为 Bearer <API_KEY>。
Content-Type	string	必填	发送 JSON 请求体时固定为 application/json。

请求体

参数	类型	是否必填	说明
model	string	必填	要调用的模型 ID，例如 gpt-5.2。
messages	array	必填	对话数组，通常每项包含 role 和 content，结构遵循 OpenAI chat 格式。
temperature	number	可选	采样温度。值越低越稳定，值越高结果越发散。
max_tokens	integer	可选	本次生成允许输出的最大 token 数。
stream	boolean	可选	设为 true 时返回 SSE 流式响应。
top_p	number	可选	核采样参数，通常作为 temperature 的替代控制项。

返回字段

响应体

参数	类型	是否必填	说明
id	string	必填	本次聊天补全结果的唯一 ID。
object	string	必填	对象类型，通常为 chat.completion。
created	integer	必填	响应创建时间的 Unix 时间戳，单位秒。
model	string	必填	实际执行本次请求的模型 ID。
choices	array	必填	模型返回的候选结果列表。
usage	object	可选	Token 使用统计信息，通常在非流式响应中返回。
request_id	string	可选	请求链路 ID，便于排障和支持定位。

choices[]

参数	类型	是否必填	说明
index	integer	必填	当前候选结果在返回数组中的索引。
message.role	string	必填	消息角色，通常为 assistant。
message.content	string	必填	模型生成的文本内容。
finish_reason	string	必填	停止原因，例如 stop、length 等。

usage

参数	类型	是否必填	说明
prompt_tokens	integer	可选	输入消息消耗的 token 数。
completion_tokens	integer	可选	输出内容消耗的 token 数。
total_tokens	integer	可选	总 token 数，通常等于 prompt_tokens 与 completion_tokens 之和。

curl — 多轮对话

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.2","temperature":0.2,"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"用一句话介绍你自己"}]}'

请求与响应约定

所有接口均以 /v1 为前缀（例如 /v1/chat/completions）。完整地址为：BASE_URL/chat/completions，其中 BASE_URL 通常为 https://api.example.com/v1。

必须携带 Authorization Header：Authorization: Bearer <API_KEY>；请求体为 JSON（Content-Type: application/json）。

建议你在业务侧为每次调用生成 traceId，并在日志中记录：request_id、模型、耗时、输入/输出 token、费用、HTTP 状态码，便于对账与排障。

成功响应通常包含 choices 与 usage（或等价字段）。如果你使用 OpenAI SDK，字段结构与 OpenAI 的返回基本一致。

通用请求头（示例）

Authorization: Bearer $API_KEY
Content-Type: application/json

成功响应结构（示例）

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 20,
    "total_tokens": 32
  },
  "request_id": "req_01HZX..."
}

流式返回（SSE）

当 stream=true 时，服务端会以 Server-Sent Events (SSE) 方式持续返回增量内容，适合长回答与实时 UI。

客户端需按事件流逐段拼接文本；当收到 [DONE]（或流结束）时表示完成。

如遇网络中断，可在应用层实现重连与超时保护。

Node.js — fetch 读取流（示意）

const res = await fetch(`${process.env.BASE_URL}/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5.2",
    stream: true,
    messages: [{ role: "user", content: "Tell me a story." }]
  })
});

for await (const chunk of res.body) {
  // 解析 SSE 并拼接增量文本
}

文生图

端点示例：POST /v1/images/generations（以模型与权限为准）。

常用参数：prompt、size；输出通常为 URL 或 base64（视实现而定）。

建议在业务侧保存生成请求与结果引用，便于审计与复现。

API 说明

https://api.example.com/v1/images/generations

OpenAI 兼容的图片生成接口。实际可用模型和字段，以当前账户开通的图片模型能力为准。

请求方法

POST

接口地址

https://api.example.com/v1/images/generations

请求参数

请求头

参数	类型	是否必填	说明
Authorization	string	必填	Bearer 鉴权头，格式为 Bearer <API_KEY>。
Content-Type	string	必填	发送 JSON 请求体时固定为 application/json。

请求体

参数	类型	是否必填	说明
model	string	必填	图片模型 ID，例如 sora-image 或其他已开通的图片模型。
prompt	string	必填	描述目标图片内容的文本提示词。
size	string	可选	目标图片尺寸，例如 1024x1024。

返回字段

响应体

参数	类型	是否必填	说明
created	integer	必填	图片生成结果创建时间的 Unix 时间戳，单位秒。
data	array	必填	生成结果列表。

data[]

参数	类型	是否必填	说明
url	string	可选	生成图片的可访问地址。当前文档示例使用该返回形式。

curl — 生成图片（示例）

curl "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sora-image","prompt":"A minimal icon in flat design","size":"1024x1024"}'

成功响应结构（示例）

{
  "created": 1774355560,
  "data": [
    {
      "url": "https://cdn.judianai.com/ai/20260324/6e149b0e0ea4e23f18de4823bc99f6c2.png"
    }
  ]
}

图生图

端点示例：POST /v1/images/edits，用于基于已有图片继续编辑或重绘。

按 OpenAI 兼容约定，可传一张或多张参考图。

核心输入为参考图、编辑提示词 prompt，以及可选输出尺寸 size。

API 说明

https://api.example.com/v1/images/edits

OpenAI 兼容的图生图接口，适合局部重绘、换背景、改元素等编辑场景。

请求方法

POST

接口地址

https://api.example.com/v1/images/edits

请求参数

请求头

参数	类型	是否必填	说明
Authorization	string	必填	Bearer 鉴权头，格式为 Bearer <API_KEY>。
Content-Type	string	必填	通常为 multipart/form-data，由客户端上传文件时自动生成边界。

请求体

参数	类型	是否必填	说明
model	string	必填	图像编辑模型 ID，例如 gpt-image-1 或当前已开通的图像编辑模型。
images	array<object>	必填	输入图片引用数组。每个元素可使用 file_id 指定已上传文件，或使用 image_url 指定完整图片 URL / base64 data URL。对于 GPT 图像模型，通常最多可提供 16 张图片。
prompt	string	必填	描述希望如何修改原图的提示词。
size	string	可选	输出图片尺寸，例如 1024x1024。

images[] 对象

参数	类型	是否必填	说明
file_id	string	可选	已通过 Files API 上传的图片文件 ID。
image_url	string	可选	完整图片 URL，或 base64 编码的 data URL。

返回字段

响应体

参数	类型	是否必填	说明
created	integer	必填	图像编辑结果创建时间的 Unix 时间戳，单位秒。
data	array	必填	编辑后的图片结果列表。

data[]

参数	类型	是否必填	说明
url	string	可选	编辑后图片的可访问地址。

curl — 图生图编辑（示例）

curl "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-1" \
  -F "image[]=@./input-1.png" \
  -F "image[]=@./input-2.png" \
  -F "prompt=将两张参考图融合成统一的电商主图风格，保留主体特征" \
  -F "size=1024x1024"

成功响应结构（示例）

{
  "created": 1774355560,
  "data": [
    {
      "url": "https://cdn.example.com/ai/edited-image.png"
    }
  ]
}

模型列表

可在“模型”页面浏览支持的模型与价格信息。

如对接 OpenAI 兼容生态，通常也会提供 GET /v1/models（可选），用于工具自动发现模型列表。

建议透明展示：按 token 计费模型显示输入/输出价格，按次模型显示每次价格；并标注可用端点类型（Chat/Images/Videos 等）。

API 说明

https://api.example.com/v1/models

可选的 OpenAI 兼容模型发现接口，供工具自动读取当前 Key 可用的模型列表。

请求方法

GET

接口地址

https://api.example.com/v1/models

请求参数

请求头

参数	类型	是否必填	说明
Authorization	string	必填	Bearer 鉴权头，格式为 Bearer <API_KEY>。

Query 参数

无额外参数。

返回字段

响应体

参数	类型	是否必填	说明
object	string	必填	对象类型，通常为 list。
data	array	必填	当前 Key 可访问的模型列表。

data[]

参数	类型	是否必填	说明
id	string	必填	模型 ID。
object	string	必填	对象类型，通常为 model。
created	integer	可选	模型记录的创建时间戳。
owned_by	string	可选	模型提供方或归属方标识。

限流与配额

常见限流指标：RPM（每分钟请求数）与 TPM（每分钟 tokens）。不同 Key / 分组 / 模型可能有不同的阈值。

触发限流通常返回 429。建议读取 Retry-After（若返回）并进行退避重试，同时在应用侧做并发控制与队列化。

大流量场景建议：拆分 Key（按项目/环境）、设置合理的 max_tokens、对长任务采用流式（SSE）与断点续传思路，并持续观察控制台的趋势与日志。

重试伪代码（示意）

for attempt in range(1, 6):
  try:
    call_api()
    break
  except RateLimitedOr5xx:
    sleep(backoff_with_jitter(attempt))
  except BadRequest4xx:
    raise

计费与限制

计费规则：我们仅对成功请求计费（例如成功返回 2xx 响应并产出有效结果）。

费用遵循所选模型定价；适用时输入/输出 tokens 分别计费；按次模型按每次调用计费。

常见限制为 RPM/TPM。触发限流时通常返回 429，建议退避重试并降低并发。

你可以在控制台查看总花费、tokens、请求数与使用日志明细，便于对账与排查。

余额查询

用于查询当前账户余额。

API 说明

https://api.example.com/v1/dashboard/billing/balance

返回当前 API Key 所属账户的余额信息。

请求方法

GET

接口地址

https://api.example.com/v1/dashboard/billing/balance

请求参数

请求头

参数	类型	是否必填	说明
Authorization	string	必填	Bearer 鉴权头，格式为 Bearer <API_KEY>。

Query 参数

无额外参数。

返回字段

响应体

参数	类型	是否必填	说明
balance	number	必填	当前账户可用余额。
currency	string	必填	余额币种代码，例如 USD。

请求示例

curl "$BASE_URL/dashboard/billing/balance" -H "Authorization: Bearer $API_KEY"

返回示例

{"balance":2375.91,"currency":"USD"}

错误与排障

建议每个响应返回 Request ID（例如在响应头或响应体中），便于定位与支持。

常见错误：鉴权失败（401/403）、模型无权限（403）、限流（429）、余额不足（402/403）、请求参数错误（400）、上游超时（504）等。

排障建议：先检查 base URL 与 API Key 是否正确，再检查 Key 的模型权限、IP 白名单、预算/到期配置，最后结合 Request ID 与日志定位具体原因。

错误响应结构（示例）

{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error",
    "code": "invalid_api_key"
  },
  "request_id": "req_01HZX..."
}

安全最佳实践

不要在前端直接调用并暴露 API Key；推荐通过你的服务端转发请求或签发短期令牌。

为 Key 配置 IP 白名单；对高风险场景开启预算限制与到期时间，并定期轮换。

对关键操作（创建/删除/启停 Key）做审计记录；生产环境建议开启告警（例如余额不足提醒）。