AI-123 · 开放平台

AI-123 开放 API 说明文档

OpenAI 兼容接口 · 对话 / 生图 / 生视频 / 模型与账户查询

🌐 HTTP API 📋 REST + SSE 流式 🔑 Bearer sk-xxx 📦 JSON 🗓 v1 · 2026-10-21

快速开始 Quick Start

AI-123 提供一套与 OpenAI 接口风格兼容的 HTTP API，覆盖对话（多模态图片理解 + SSE 流式）、文生图 / 图生图、文生视频 / 图生视频、模型与账户查询。只需三步即可接入：

  1. 创建 API 密钥：登录后进入「开放 API」页面，创建一枚密钥（形如 sk-xxxx…）。
  2. 携带密钥发起请求：所有请求都要在 Authorization 头里带上 Bearer sk-xxx。
  3. 调用对应端点：生图同步返回结果；生视频异步返回任务 ID，再用任务查询接口轮询拿到成片。
💡 计费说明 所有生成类接口（对话 / 生图 / 生视频）会按所调模型的价格实时扣减账户余额。扣费口径以「获取模型列表」接口返回的 price 为准，成功后结算、失败自动退款，请放心接入。

鉴权说明 Authentication

所有接口都要求通过 API 密钥鉴权。在请求头里携带：

HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥说明：

接口根地址 Base URL

所有端点都挂在 /v1 前缀下。以本站主域名为例：

Base URL
https://www.ai-123.top/v1

下文出现的相对路径（如 /v1/models）都指在该根地址后面拼接。

响应与错误格式 Response & Errors

接口返回体统一为 JSON，但查询类与生成类信封不同，请注意区分：

① 查询类接口（模型列表 / 账户余额 / 任务查询）

成功返回 { code: 0, data: … }：

JSON
{
  "code": 0,
  "data": { ... }
}
② 生成类接口（对话 / 生图 / 生视频）

成功时直接返回业务数据（无 code 信封），如生视频提交返回：

JSON
{
  "created": 1750000000000,
  "task_id": "……",
  "status": "PROCESSING",
  "data": [],
  "cost": 0.42
}

③ 错误响应

任何错误（参数错误、鉴权失败、余额不足、生成失败等）统一返回：

JSON
{
  "code": 400,          // HTTP 状态码同此值
  "message": "错误原因描述"
}
⚠️ 生图接口例外生图接口（POST /v1/images/generations）已统一为 OpenAI 通用格式，其错误返回采用 OpenAI 标准结构 { "error": { "message", "type", "param", "code" } }，而非上方 { code, message }。详见「08. 生图」章节。

常见状态码

状态码含义
400请求参数错误 / 余额不足 / 触发敏感词
401缺少或无效的 API 密钥
403无权限（开放接口未开启 / 账号被禁用）
404资源不存在（如任务 ID 不存在或不属于当前密钥）
429触发限速（免费模型频次受限）
500服务器内部错误
502生成失败（费用已自动退回）
503系统维护中，开放接口暂不可用

05. 获取模型列表 GET /v1/models

GET/v1/models

返回平台对外开放的模型列表及其计费价格。可选 type 参数按类型过滤（chat / image / video / audio）。

请求示例

cURL
curl "https://www.ai-123.top/v1/models?type=video" \
  -H "Authorization: Bearer sk-xxx"

响应示例

JSON
{
  "code": 0,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "Seedance 1.0 Pro",   // 调用时使用的 model 值
        "object": "model",
        "created": 1750000000,
        "owned_by": "渠道品牌",
        "type": "video",          // chat / image / video / audio
        "price": "0.42"             // 计费单价（字符串，可能为小数）
      }
    ]
  }
}
⚠️ 重要调用生成接口时，model 字段请填写列表里返回的 id（即模型展示名）。

06. 查询账户余额 GET /v1/account

GET/v1/account

返回当前密钥所属账户的余额信息，以及最近 20 条充值 / 消费 / 退款流水。

请求示例

cURL
curl "https://www.ai-123.top/v1/account" \
  -H "Authorization: Bearer sk-xxx"

响应示例

JSON
{
  "code": 0,
  "data": {
    "email": "user@example.com",
    "nickname": "示例用户",
    "balance": 88.6,                       // 当前余额（元）
    "currency": "CNY",
    "is_agent": false,                    // 是否为代理商
    "recent_transactions": [ /* 交易流水 */ ]
  }
}

07. 对话（含流式） POST /v1/chat/completions

POST/v1/chat/completions

发起对话，兼容 OpenAI Chat Completions 结构。支持多模态（图片理解）与 SSE 流式输出。

请求体字段

字段类型必填说明
modelstring必填模型名称（模型列表接口返回的 id）
messagesarray必填对话消息数组，每条含 role（user/assistant/system）与 content
temperaturenumber可选采样温度，0 ~ 2，默认按模型设定
streamboolean可选是否流式返回（SSE）；默认 false

多模态（图片理解）content 结构

当模型支持图片理解时，content 可为内容块数组，混合文本与图片：

JSON
{
  "role": "user",
  "content": [
    { "type": "text", "text": "描述一下这张图" },
    { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
  ]
}

非流式请求示例

cURL
curl "https://www.ai-123.top/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名称",
    "messages": [{"role":"user","content":"你好"}]
  }'

非流式响应示例

JSON
{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "模型名称",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 18 },
  "cost": 0.0001
}

流式（SSE）输出

设置 "stream": true 后，服务端以 text/event-stream 逐段推送，每段格式：

SSE
data: {"id":"chatcmpl-xxxx","object":"chat.completion.chunk","created":1750000000,"model":"模型名称","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxxx",...,"choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxxx",...,"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":18},"cost":0.0001}

data: [DONE]

客户端逐行读取，遇到 data: [DONE] 表示结束；最后一条携带 finish_reason: "stop" 与 usage / cost。

08. 生图 POST /v1/images/generations

POST/v1/images/generations

文本或参考图生图。同步返回：服务端会等出图完成后一次性返回结果（最长约 8 分钟），无需轮询。

请求体字段

字段类型必填说明
modelstring必填模型名称
promptstring必填描述文字（≤4000 字）
nnumber可选单批张数，默认 1，上限由模型配置决定（一般 ≤8）
sizestring可选画幅尺寸，如 1024x1024
resolutionstring可选清晰度档位（1K/2K/3K/4K），仅后台配置了档位的模型生效
imagestring | string[]可选参考图 URL（图生图用）；一次最多传几张由模型后台配置决定（未配置默认 4 张）
extraobject可选扩展参数（一般不用，用于实现一些特殊效果）

文生图请求示例

cURL
curl "https://www.ai-123.top/v1/images/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名称",
    "prompt": "一只戴着宇航员头盔的柯基犬，赛博朋克风格",
    "n": 1,
    "size": "1024x1024"
  }'

图生图请求示例

JSON
{
  "model": "模型名称",
  "prompt": "把这张照片重绘成水彩插画风格",
  "image": [
    "https://example.com/ref1.jpg",
    "https://example.com/ref2.jpg"
  ],
  "n": 1
}

响应示例（成功）

JSON
{
  "created": 1750000000,
  "data": [
    { "url": "https://cdn.ai-123.top/uploads/xxx.png" },
    { "url": "https://cdn.ai-123.top/uploads/yyy.png" }
  ]
}

成功响应与 OpenAI images/generations 完全一致：created 为 Unix 秒级时间戳，data 数组每个元素为 { "url": "..." }。

响应示例（失败）

JSON
{
  "error": {
    "message": "生成失败，费用已退回",
    "type": "api_error",
    "param": null,
    "code": null
  }
}

失败响应采用 OpenAI 标准错误结构 { "error": { ... } }，type 取值：invalid_request_error（参数错误）/ authentication_error（鉴权失败）/ permission_error（无权限，如接口未开启或账号被禁用）/ not_found_error（模型不存在）/ rate_limit_error（限速）/ api_error（服务端或生成失败）。

💡 超时行为若等待超时仍未出图（超过约 8 分钟），接口按 OpenAI 错误格式返回 502 超时错误（任务仍在后台执行），请稍后重试或联系客服。

09. 生视频 POST /v1/videos/generations

POST/v1/videos/generations

文本 / 图 / 音频 / 视频生视频。异步返回：提交后立即返回任务 ID，需用「任务查询」接口轮询拿到成片。

请求体字段

字段类型必填说明
modelstring必填模型名称
promptstring必填描述文字（≤4000 字）
secondsnumber可选时长（秒），1 ~ 600，实际按模型能力收敛
sizestring可选画面比例，如 16:9 / 9:16
imagestring | string[]可选参考图 URL；一次最多传几张由模型后台配置决定（未配置默认 30 张，超出部分会被忽略）
audiostring | string[]可选参考音频 URL（只有支持参考音频的模型才生效，最多传几张由模型后台配置决定）
videostring | string[]可选参考视频 URL（只有支持参考视频的模型才生效，最多传几张由模型后台配置决定）
first_framestring可选首帧图 URL。给首尾帧让模型生成中间过渡画面（需模型支持该能力）
last_framestring可选尾帧图 URL。与 first_frame 搭配，两个至少填一个
extraobject可选扩展参数（一般不用）

图生视频（含参考音频 / 视频）请求示例

JSON
{
  "model": "模型名称",
  "prompt": "让画面中的角色眨眼并微笑，镜头轻微推近",
  "image": [
    "https://example.com/ref1.jpg",
    "https://example.com/ref2.jpg"
  ],
  "audio": [ "https://example.com/ref.mp3" ],
  "video": [ "https://example.com/ref.mp4" ],
  "seconds": 15
}

首尾帧生视频请求示例

JSON
{
  "model": "模型名称",
  "prompt": "从清晨的城市街景平滑过渡到夜晚的霓虹夜景",
  "first_frame": "https://example.com/first.jpg",
  "last_frame": "https://example.com/last.jpg",
  "seconds": 8
}

响应示例（受理成功）

JSON
{
  "created": 1750000000000,
  "task_id": "……",
  "status": "PROCESSING",
  "data": [],
  "cost": 0.42
}
💡 关于参考素材（一句话看懂） 参考图 / 音频 / 视频 / 首尾帧都是可选的，不传就纯靠文字描述生成。
传了之后是否真正生效，取决于你调的模型支不支持这种素材：支持的模型会用它，不支持的会安全忽略（不会报错，也不会多扣钱）。
想知道某个模型支持哪些素材，请查看「模型列表」接口里的说明，或直接问客服。

10. 查询任务结果 GET /v1/tasks/{id}

GET/v1/tasks/{id}

按任务 ID 查询异步任务（生视频）的状态与结果。生图已同步返回，无需轮询。

请求示例

cURL
curl "https://www.ai-123.top/v1/tasks/替换为task_id" \
  -H "Authorization: Bearer sk-xxx"

响应示例

JSON
{
  "code": 0,
  "data": {
    "id": "……",
    "type": "video",
    "status": "SUCCESS",          // PROCESSING / SUCCESS / FAILED
    "progress": 100,
    "created": 1750000000000,
    "finished": 1750000100000,
    "cost": 0.42,
    "error": null,
    "prompt": "原始提示词",
    "data": [
      { "url": "https://cdn.ai-123.top/uploads/xxx.mp4" }
    ]
  }
}

任务状态说明

状态含义
PROCESSING生成中，请稍后再次轮询
SUCCESS成功，结果在 data[].url
FAILED失败，原因见 error（费用已退回）

11. 完整代码示例 Examples

Python

Python
import requests

BASE = "https://www.ai-123.top/v1"
KEY = "sk-xxx"
H = {"Authorization": f"Bearer {KEY}"}

# 1. 获取模型列表
r = requests.get(f"{BASE}/models", headers=H)
print("models:", r.json())

# 2. 生视频（异步）
r = requests.post(f"{BASE}/videos/generations", headers=H, json={
    "model": "模型名称",
    "prompt": "镜头缓慢推进，雨夜霓虹街道上行人撑伞走过",
    "seconds": 15,
})
task = r.json()["task_id"]
print("task_id:", task)

# 3. 轮询任务直到完成
import time
while True:
    res = requests.get(f"{BASE}/tasks/{task}", headers=H).json()["data"]
    if res["status"] in ("SUCCESS", "FAILED"):
        print("final:", res)
        break
    time.sleep(5)

Node.js

JavaScript
const BASE = "https://www.ai-123.top/v1";
const KEY = "sk-xxx";

// 对话（非流式）
const res = await fetch(`${BASE}/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "模型名称",
    messages: [{ role: "user", content: "你好" }],
  }),
});
console.log(await res.json());

cURL（对话流式）

cURL
curl -N "https://www.ai-123.top/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"模型名称","messages":[{"role":"user","content":"你好"}],"stream":true}'

12. 常见问题 FAQ

Q：生图接口超时了怎么办？

生图正常是同步返回的。仅在等待超过约 8 分钟仍未出图时才会返回 502 超时错误（OpenAI 错误格式 { "error": { ... } }），此时任务仍在后台执行，请稍后重试或联系客服。

Q：扣费失败会怎样？

生成失败时费用会自动退回账户，无需额外操作。对话接口按 token 实时结算，余额不足会返回 400。

Q：参考图 / 音频 / 视频传了但没生效？

参考素材是否生效取决于所调模型是否支持对应类型；不支持时会安全丢弃而非报错。请先确认模型能力。

Q：如何获取密钥？

登录后进入「开放 API」页面，即可创建、复制、删除 API 密钥。

Q：first_frame / last_frame 两个字段必须同时填吗？

不必。两个至少填一个就行——只填首帧、只填尾帧、首尾都填都可以。具体效果取决于模型能力。