文档 / API 参考Docs / API Reference

API 参考API Reference

面向文本、图像、视频、音频与模型管理的统一接口文档。所有接口使用 Unified API documentation for text, image, video, audio, and model management. All endpoints use Authorization: Bearer <Token> 鉴权,请求示例中的 for authentication. In the request examples, {BASE_URL} 为平台服务地址,OpenAI SDK 通常配置为 denotes the platform service address, typically configured as {BASE_URL}/v1。 in OpenAI SDKs.

7 个接口endpoints
5 个分类categories
OpenAI 兼容OpenAI Compatible AI 友好AI friendly
异步任务Async Tasks 视频生成Video Generation

生文Text Generation

对话补全Chat Completions

POST /v1/chat/completions

OpenAI 兼容的对话补全接口,是文本生成的主要入口,支持流式输出、工具调用与多模态输入。OpenAI-compatible chat completions endpoint — the primary entry point for text generation, supporting streaming output, tool calling, and multimodal input.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required模型名称Model name"gpt-4o"
messagesarray必填Required对话消息数组,每条含 role 与 contentArray of chat messages, each with role and content[{"role":"user","content":"你好"}]
streamboolean可选Optional是否流式返回,true 时以 SSE 逐段输出Whether to stream the response; when true, output is delivered incrementally via SSEtrue
max_tokensinteger可选Optional单次生成的最大输出 token 数Maximum number of output tokens per generation4096
temperaturefloat可选Optional采样温度,范围 0-2,值越大输出越随机Sampling temperature, range 0–2; higher values make output more random0.7
top_pfloat可选Optional核采样,范围 0-1Nucleus sampling, range 0–10.9
stopstring/array可选Optional停止词,命中即终止生成Stop sequences; generation terminates on a match"\n"
frequency_penaltyfloat可选Optional频率惩罚,范围 -2~2Frequency penalty, range -2 to 20
presence_penaltyfloat可选Optional存在惩罚,范围 -2~2Presence penalty, range -2 to 20
toolsarray可选Optional工具 / 函数定义列表List of tool / function definitions-
tool_choicestring/object可选Optional工具选择策略(auto / none / required)Tool selection strategy (auto / none / required)"auto"
response_formatobject可选Optional输出格式约束Output format constraint{"type":"json_object"}
userstring可选Optional用户标识User identifier-

响应示例Response Example

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好!有什么可以帮你?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}

适用模型Supported Models

对话 / 推理类模型Chat / reasoning models支持流式与工具调用Streaming and tool calling supported

示例代码Example Code

curl {BASE_URL}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{ "role": "user", "content": "你好" }],
    "stream": false
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="{BASE_URL}/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "{BASE_URL}/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

生图Image Generation

图片生成Image Generation

POST /v1/images/generations

OpenAI 兼容的文生图 / 图生图入口,支持尺寸、质量与数量参数。OpenAI-compatible text-to-image / image-to-image entry point, supporting size, quality, and quantity parameters.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required模型名称Model name"gpt-image-2"
promptstring必填Required图片描述文本Text describing the image to generate"一只猫在花园里弹钢琴"
sizestring可选Optional图片尺寸,如 1024x1024Image size, e.g. 1024x1024"1024x1024"
qualitystring可选Optional图片质量(low / medium / high)Image quality (low / medium / high)"high"
ninteger可选Optional生成图片数量Number of images to generate1
response_formatstring可选Optional返回格式(url / b64_json)Response format (url / b64_json)"url"

响应示例Response Example

{
  "created": 1700000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "优化后的提示词"
    }
  ]
}

适用模型Supported Models

文生图模型Text-to-image models图生图模型Image-to-image models

示例代码Example Code

curl {BASE_URL}/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只猫在花园里弹钢琴",
    "size": "1024x1024",
    "n": 1
  }'
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="{BASE_URL}/v1")

resp = client.images.generate(
    model="gpt-image-2",
    prompt="一只猫在花园里弹钢琴",
    size="1024x1024",
)
print(resp.data[0].url)
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "{BASE_URL}/v1" });
const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "一只猫在花园里弹钢琴",
  size: "1024x1024",
});
console.log(resp.data[0].url);

图片编辑Image Edit

POST /v1/images/edits

基于参考图与编辑指令修改图片,支持 URL 透传模式,避免 base64 体积与延迟。Modify images based on a reference image and editing instructions, with URL pass-through mode to avoid base64 payload size and latency.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required模型名称Model name"gpt-image-edit"
imagestring必填Required参考图,支持 URL 或 base64Reference image, URL or base64 supported"https://..."
promptstring必填Required编辑指令描述Description of the editing instruction"把背景改为夜晚"
sizestring可选Optional输出图片尺寸Output image size"1024x1024"
ninteger可选Optional生成图片数量Number of images to generate1

响应示例Response Example

{
  "created": 1700000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "优化后的提示词"
    }
  ]
}

适用模型Supported Models

图片编辑类模型Image editing models

示例代码Example Code

curl {BASE_URL}/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-edit" \
  -F "image=https://example.com/image.jpg" \
  -F "prompt=把背景改为夜晚"
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="{BASE_URL}/v1")

resp = client.images.edit(
    model="gpt-image-edit",
    image="https://example.com/image.jpg",
    prompt="把背景改为夜晚",
)
print(resp.data[0].url)
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "{BASE_URL}/v1" });
const resp = await client.images.edit({
  model: "gpt-image-edit",
  image: "https://example.com/image.jpg",
  prompt: "把背景改为夜晚",
});
console.log(resp.data[0].url);

生视频Video Generation

视频生成Video Generation

POST /v1/videos/generations

异步视频生成任务提交接口。提交后立即返回任务 ID(Async video generation task submission endpoint. Returns a task ID immediately after submission (status=queued),随后通过查询接口轮询任务状态,成功后再取视频 URL。), then poll the task status via the query endpoint and fetch the video URL once it succeeds.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required视频模型名称Video model name"kling-v3"
promptstring必填Required视频描述文本Text describing the video"一只猫在花园里弹钢琴"
sizestring可选Optional分辨率,如 540p / 720p / 1080pResolution, e.g. 540p / 720p / 1080p"540p"
secondsinteger可选Optional期望时长(秒),实际生成时长以模型为准Desired duration (seconds); actual duration is determined by the model5
imagestring可选Optional参考图 URL,用于图生视频Reference image URL for image-to-video"https://..."

响应示例Response Example

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}

适用模型Supported Models

文生视频模型Text-to-video models图生视频模型Image-to-video models

示例代码Example Code

curl {BASE_URL}/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "一只猫在花园里弹钢琴,电影感镜头,柔和光线",
    "size": "540p",
    "seconds": 5
  }'
import requests

resp = requests.post(
    "{BASE_URL}/v1/videos/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-v3",
        "prompt": "一只猫在花园里弹钢琴,电影感镜头,柔和光线",
        "size": "540p",
        "seconds": 5,
    },
)
task_id = resp.json()["task_id"]
print(task_id)
const resp = await fetch("{BASE_URL}/v1/videos/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "kling-v3",
    prompt: "一只猫在花园里弹钢琴,电影感镜头,柔和光线",
    size: "540p",
    seconds: 5,
  }),
});
const data = await resp.json();
console.log(data.task_id);

查询视频任务Query Video Task

GET /v1/videos/generations/{task_id}

查询异步视频任务的状态与生成结果,轮询直至 Query the status and result of an async video task; poll until status=succeeded 后取 and then use result_url 下载视频。 to download the video.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
task_idpath必填Required提交视频生成任务返回的任务 IDTask ID returned when submitting the video generation task"task_xxxxxxxx"

响应示例Response Example

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "succeeded",
  "progress": "100%",
  "result_url": "https://..."
}

适用模型Supported Models

全部视频模型All video models

示例代码Example Code

curl {BASE_URL}/v1/videos/generations/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"
import requests

resp = requests.get(
    "{BASE_URL}/v1/videos/generations/task_xxxxxxxx",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = resp.json()
print(data["status"], data.get("result_url"))
const resp = await fetch(
  "{BASE_URL}/v1/videos/generations/task_xxxxxxxx",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } },
);
const data = await resp.json();
console.log(data.status, data.result_url);

生音频Audio Generation

语音合成Speech Synthesis

POST /v1/audio/speech

文本转语音(TTS),输入文本与音色,返回音频字节流。Text-to-speech (TTS): provide text and a voice, and receive an audio byte stream.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required语音合成模型名称Speech synthesis model name"tts-1"
inputstring必填Required要合成的文本Text to synthesize"你好,世界"
voicestring可选Optional音色Voice"alloy"
response_formatstring可选Optional音频格式(mp3 / wav 等)Audio format (mp3 / wav, etc.)"mp3"

响应示例Response Example

# Audio byte stream
# Content-Type: audio/mpeg

适用模型Supported Models

语音合成(TTS)模型Speech synthesis (TTS) models

示例代码Example Code

curl {BASE_URL}/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "你好,世界",
    "voice": "alloy"
  }' \
  -o speech.mp3
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="{BASE_URL}/v1")

resp = client.audio.speech.create(
    model="tts-1",
    input="你好,世界",
    voice="alloy",
)
resp.stream_to_file("speech.mp3")
import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "{BASE_URL}/v1" });
const resp = await client.audio.speech.create({
  model: "tts-1",
  input: "你好,世界",
  voice: "alloy",
});
const buffer = Buffer.from(await resp.arrayBuffer());
fs.writeFileSync("speech.mp3", buffer);

语音转写Speech Transcription

POST /v1/audio/transcriptions

语音识别(STT),multipart 上传音频文件,返回识别文本。Speech-to-text (STT): upload an audio file via multipart and receive the transcribed text.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
modelstring必填Required语音转写模型名称Speech transcription model name"whisper-1"
filefile必填Required音频文件(multipart/form-data)Audio file (multipart/form-data)audio.mp3
languagestring可选Optional音频语言(ISO 639-1)Audio language (ISO 639-1)"zh"

响应示例Response Example

{
  "text": "你好,世界"
}

适用模型Supported Models

语音转写(STT)模型Speech transcription (STT) models

示例代码Example Code

curl {BASE_URL}/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=whisper-1" \
  -F "file=@audio.mp3"
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="{BASE_URL}/v1")

with open("audio.mp3", "rb") as f:
    resp = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
    )
print(resp.text)
import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "{BASE_URL}/v1" });
const resp = await client.audio.transcriptions.create({
  model: "whisper-1",
  file: fs.createReadStream("audio.mp3"),
});
console.log(resp.text);

其他Others

模型列表Model List

GET /v1/models

查询当前 Token 可调用的全部模型列表。List all models callable with the current Token.

鉴权方式Authentication

Authorization: Bearer <Token>

请求参数Request Parameters

参数Parameter类型Type必填Required说明Description示例Example
---无请求参数No request parameters-

响应示例Response Example

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "openai"
    }
  ]
}

适用模型Supported Models

全部已授权模型All authorized models

示例代码Example Code

curl {BASE_URL}/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="{BASE_URL}/v1")
models = client.models.list()
for m in models.data:
    print(m.id)
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "{BASE_URL}/v1" });
const models = await client.models.list();
for (const m of models.data) {
  console.log(m.id);
}

错误码Error Codes

HTTP 状态码HTTP Status Code含义Meaning处理建议Suggested Action
401鉴权失败Authentication failed检查 Token 是否有效、是否过期或已删除,重新在「令牌」页面创建。Check whether the Token is valid, expired, or deleted, then create a new one on the Tokens page.
403权限不足 / 模型未配置价格Insufficient permissions / model price not configured确认账号对该模型有访问权限,或模型已上线并配置价格。Confirm the account has access to the model, or that the model is live with its price configured.
404接口或模型不存在Endpoint or model not found确认请求路径与 Verify the request path and the model 参数是否正确。 parameter are correct.
429余额不足或请求过于频繁Insufficient balance or requests too frequent前往「充值」页面充值,或降低请求频率后重试。Top up on the Top-up page, or retry with a lower request rate.
5xx平台服务异常Platform service error稍后重试;若持续出现,可通过工单反馈。Retry later; if the issue persists, report it via a support ticket.

限制与建议Limits and Recommendations

  • 所有请求必须携带 All requests must include the Authorization: Bearer <Token> 请求头。 header.
  • 视频生成为异步任务,请以任务 ID 轮询查询,避免重复提交。Video generation is an async task; poll it by task ID instead of resubmitting.
  • 大模型输出可能包含不准确内容,生产环境请自行做好内容校验。Model output may contain inaccurate content; perform your own content validation in production.