WUJIE AI API 文档
OpenAI 兼容接口,包含 WUJIE AI 视频与 Realtime 扩展。使用一个统一地址, 调用平台已配置的全部 AI 模型。
快速开始
创建 API Key,将 Base URL 指向本平台,然后继续使用熟悉的 OpenAI SDK。
不同应用分别创建,并按需限制接口、模型、RPM、TPM、并发、累计/每日/每月额度及预警线。
不要写进浏览器代码、移动端包或公开仓库。
模型 ID 使用 GET /v1/models 返回的列表,不要填写上游供应商的内部模型名。
curl "https://ai.wujie.ltd/v1/chat/completions" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.2",
"messages": [{"role": "user", "content": "你好,请介绍一下你自己"}]
}'
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["AIGATE_API_KEY"],
base_url="https://ai.wujie.ltd/v1",
)
resp = client.chat.completions.create(
model="glm-5.2",
messages=[{"role": "user", "content": "你好,请介绍一下你自己"}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.AIGATE_API_KEY,
baseURL: "https://ai.wujie.ltd/v1",
});
const resp = await client.chat.completions.create({
model: "glm-5.2",
messages: [{ role: "user", content: "你好,请介绍一下你自己" }],
});
console.log(resp.choices[0].message.content);
流式响应
设置 stream: true 后返回 SSE。使用 curl 时加 -N 禁用客户端缓冲。
curl -N "https://ai.wujie.ltd/v1/chat/completions" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.2",
"stream": true,
"messages": [{"role": "user", "content": "写一个简短的产品介绍"}]
}'
data: [DONE],提前断开仍会由后台完成结算或异常退款。
Responses API
需要使用 OpenAI Responses 风格输入时,调用 POST /responses。
curl "https://ai.wujie.ltd/v1/responses" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"glm-5.2","input":"解释什么是 API 网关"}'
Embeddings API
将文本转换为向量,用于语义检索、聚类和 RAG。请选择标有 Embeddings 能力的模型。
curl "https://ai.wujie.ltd/v1/embeddings" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gemini-3.1-flash-lite","input":["向量检索示例文本","支持批量输入"]}'
stream。图像生成 API
支持文字生成图片和图片编辑,按实际成功返回的图片张数结算。
n 表示请求张数(1–10)。
网关先按 n 预占余额,成功后按上游实际返回张数结算并释放差额;失败请求不扣费。
#Qwen Image 3.0 · OpenAI compatibility
Qwen Image 3.0 模型继续使用相同的 OpenAI 兼容接口。WUJIE AI 会将
model、prompt、1–3 张参考图、
n(1–6)、size、
negative_prompt、seed、
watermark、提示词扩写和思考控制映射到阿里云百炼。
渠道 Provider 请选择 DashScope,并使用区域一致的 Base URL、模型和 API Key。
请求参数
POST /v1/images/generations · POST /v1/images/edits
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 已启用的图像模型 ID,请使用 GET /v1/models 返回的模型 ID。 |
prompt | string | 是 | 文生图的提示词,或图片编辑指令。 |
image | file/object | 仅图片编辑 | /v1/images/edits 必填;支持 multipart 图片文件,或 JSON 图片对象/数据 URL。 |
n | integer | 否 | 请求生成张数;默认 1,取值范围 1–10。 |
size | string | 否 | 可选尺寸或质量控制。通用值:512、1K、2K、4K、1024x1024、1536x1024、1024x1536。 |
aspect_ratio | string | 否 | 可选宽高比。Gemini 支持 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:8、8:1、1:4、4:1;GPT Image 会将 16:9 和 9:16 转换为对应支持尺寸。 |
stream: true。
其他 provider 专属字段只有在所选上游支持时才可用。
文字生成图片 · POST /v1/images/generations
curl "https://ai.wujie.ltd/v1/images/generations" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean blue WUJIE AI logo on a white background",
"size": "1024x1024",
"n": 1
}'
图片编辑 · POST /v1/images/edits
curl "https://ai.wujie.ltd/v1/images/edits" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=Keep the subject and replace the background with a clean blue studio" \
-F "image=@source.png" \
-F "n=1"
兼容旧接口 POST /v1/images。调用日志会记录请求张数、实际生成张数以及是否采用估算结算。
视频生成 API
同一个对外接口支持所有已配置的视频模型的文生视频和图生视频。
/v1/models 返回的模型 ID。
#当前可用的视频模型
POST /v1/videos 请使用以下模型 ID。列表反映当前 API Key 实际可访问的模型。
创建请求前请先读取 /v1/models 返回的
video_constraints,其中包含模型支持的时长、宽高比、分辨率及条件规则;
不支持的组合会在提交上游前被拒绝。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 已启用的视频模型 ID |
prompt | string | 是 | 视频描述 |
image | file/object | 图生视频必填 | multipart JPEG/PNG 文件,或 JSON { mime_type, data } 图片对象 |
duration_seconds | integer | — | 视频时长(秒),未填写时使用模型默认时长 |
aspect_ratio | string | — | 视频比例,例如 16:9 或 9:16 |
resolution | string | — | 模型支持的分辨率,例如 480p、720p 或 1080p |
文生视频 · POST /v1/videos
curl.exe "https://ai.wujie.ltd/v1/videos" `
-H "Authorization: Bearer $env:AIGATE_API_KEY" `
-F "model=grok-imagine-video" `
-F "prompt=A cinematic blue logo animation on a clean white background" `
-F "duration_seconds=8" `
-F "aspect_ratio=16:9"
图生视频(multipart 文件)· POST /v1/videos
curl.exe "https://ai.wujie.ltd/v1/videos" `
-H "Authorization: Bearer $env:AIGATE_API_KEY" `
-F "model=grok-imagine-video" `
-F "prompt=Bring this still image to life with a slow cinematic camera move" `
-F "image=@source.jpg;type=image/jpeg" `
-F "duration_seconds=8" `
-F "aspect_ratio=16:9"
图生视频(JSON image 对象)· POST /v1/videos
$imageBase64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("source.jpg"))
$headers = @{ Authorization = "Bearer $env:AIGATE_API_KEY"; "Content-Type" = "application/json" }
$body = @{
model = "grok-imagine-video"
prompt = "Bring this still image to life with a slow cinematic camera move"
image = @{ mime_type = "image/jpeg"; data = $imageBase64 }
duration_seconds = 8
aspect_ratio = "16:9"
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "https://ai.wujie.ltd/v1/videos" -Headers $headers -Body $body
查询任务状态 · GET /v1/videos/{id}
$headers = @{ Authorization = "Bearer $env:AIGATE_API_KEY" }
Invoke-RestMethod -Method Get -Uri "https://ai.wujie.ltd/v1/videos/VIDEO_ID" -Headers $headers
获取视频文件 · GET /v1/videos/{id}/content
$headers = @{ Authorization = "Bearer $env:AIGATE_API_KEY" }
Invoke-WebRequest -Method Get `
-Uri "https://ai.wujie.ltd/v1/videos/VIDEO_ID/content" `
-Headers $headers -OutFile "wujie-video-output.mp4"
id 和 status: processing。
请轮询至 completed 或 failed,再使用 WUJIE AI 的 content 地址下载;
供应商地址和密钥始终留在服务端。xAI 过期任务会以 failed 和对应错误码返回。
PowerShell 请先设置 $env:AIGATE_API_KEY。
实时语音 Realtime
Realtime 模型必须使用 WebRTC 和专用 Realtime 接口,不能提交到
/v1/chat/completions。
#当前可用的 Realtime 模型
实际可用列表以 GET /v1/models 返回为准。
#正确连接流程
sk-gw-* API Key 写入浏览器代码。应由你自己的后端调用
/v1/realtime/client_secrets,前端只接收临时的
ek_aigate_* 密钥。
第 1 步 · 服务端创建一次性客户端密钥
$apiKey = $env:AIGATE_API_KEY
$body = @{
session = @{
type = 'realtime'
model = 'gemini-3.1-flash-lite'
}
} | ConvertTo-Json -Depth 5
$secret = Invoke-RestMethod `
-Method Post `
-Uri 'https://ai.wujie.ltd/v1/realtime/client_secrets' `
-Headers @{ Authorization = "Bearer $apiKey" } `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$secret.value # ek_aigate_*,90 秒有效且仅可使用一次
第 2 步 · 浏览器建立 WebRTC 连接
// temporaryKey 由你自己的后端获取,值为 ek_aigate_*,不要在浏览器中放 sk-gw-*。
const temporaryKey = await fetch("/your-backend/realtime-token")
.then((response) => response.text());
const pc = new RTCPeerConnection();
const audio = document.createElement("audio");
audio.autoplay = true;
pc.ontrack = (event) => { audio.srcObject = event.streams[0]; };
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
mic.getTracks().forEach((track) => pc.addTrack(track, mic));
pc.createDataChannel("oai-events");
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const answerSdp = await fetch("https://ai.wujie.ltd/v1/realtime/calls", {
method: "POST",
headers: {
Authorization: `Bearer ${temporaryKey}`,
"Content-Type": "application/sdp",
},
body: offer.sdp,
}).then((response) => response.text());
await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });
接口列表
所有模型接口使用相同的 Bearer API Key。
POST /v1/images/generations 文生图 ·
POST /v1/images/edits 图生图 ·
POST /v1/videos 创建视频任务(按秒计费)。
安全重试
非流式 POST 请求可使用 Idempotency-Key,
避免网络超时重试造成重复调用和重复扣费。
24 小时幂等窗口
curl "https://ai.wujie.ltd/v1/chat/completions" \
-H "Authorization: Bearer $AIGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20260716-001" \
-d '{"model":"glm-5.2","messages":[{"role":"user","content":"生成订单摘要"}]}'
- 客户端生成唯一值:每次业务操作生成一个 1–200 字节的唯一键;同一次重试必须复用相同键和完全相同的请求体。
- 识别重放响应:命中已完成记录时返回原始状态、正文和
X-Request-ID,并附加Idempotency-Replayed: true。 - 仅支持非流式请求:Chat Completions、Responses 和 Embeddings 的非流式 POST 均支持;
stream: true携带该请求头会返回 400。
Idempotency-Key 重试,可取回断线期间完成的最终响应;
调用日志会明确标记“客户端断线”。
错误与限流
平台本地错误统一使用 { error: { message, type, code } }。
| HTTP | 错误 code | 含义 | 处理建议 |
|---|---|---|---|
| 400 | invalid_json max_output_tokens_exceeded |
JSON、参数或输出上限错误 | 检查 model、messages/input 与最大输出 Token |
| 400 | invalid_endpoint invalid_token_estimate |
试算接口或 Token 构成无效 | 检查 endpoint、缓存输入、上下文与最大输出 |
| 401 | invalid_api_key | API Key 无效 | 检查 Bearer、状态和过期时间 |
| 402 | api_key_quota_exceeded | 此 Key 的独立额度不足 | 提高或清除该 Key 的独立额度 |
| 402 | insufficient_balance | 账户余额不足 | 为账户充值或联系运营调整余额 |
| 403 | ip_not_allowed model_not_allowed |
IP、接口或模型未授权 | 检查此 Key 的访问策略 |
| 409 | idempotency_key_conflict idempotency_in_progress |
幂等键对应不同请求,或原请求仍在处理 | 冲突时换新键;处理中按 Retry-After 重试 |
| 413 | request_too_large | 请求体过大 | 缩短输入或拆分请求 |
| 429 | rpm_limit_exceeded tpm_limit_exceeded |
RPM、TPM 或并发超限 | 读取 Retry-After 与 X-RateLimit-*,指数退避 |
| 502 | upstream_unavailable | 上游调用失败 | 携带 X-Request-ID 联系运营 |
| 502 | upstream_outcome_uncertain | 请求已写入上游但结果待核查 | 不要重复提交;保留 X-Request-ID 等待平台核账 |
| 503 | model_unavailable gateway_paused |
无可用路由或平台维护 | 读取错误 code 与 Retry-After |
错误响应示例
{
"error": {
"message": "请求频率超过 API Key 限制",
"type": "rate_limit_error",
"code": "rpm_limit_exceeded"
}
}
安全与可靠性
生产应用应把 API Key 当作密码管理。
| 建议 | 说明 |
|---|---|
| 仅放在服务端 | 使用环境变量或密钥管理器,禁止嵌入网页和客户端应用。 |
| 按应用隔离 | 每个环境和服务使用独立 Key,泄露时只停用受影响密钥。 |
| 设置额度与限流 | 按业务选择累计、每日或每月额度,并配置 RPM、TPM 与并发。 |
| 记录请求 ID | 保存响应头 X-Request-ID;平台不保存 Prompt 正文,排障依赖该 ID。 |