UG AI 中心UG AI 中心/API 文档

API 文档

统一视频 / 图像 / 文本生成 API 网关。通过一个接口接入多家 AI Provider，自动路由、限流、用量统计。

健康检查管理后台

快速接入 (3 步)

01

获取 API Key

登录管理后台 → Key 管理 → 创建 Key，复制完整密钥（仅显示一次）

02

提交生成任务

POST /api/video/submit，带上 Authorization: Bearer sk_xxx，返回 jobId

03

轮询任务状态

GET /api/video/status?jobId=xxx，status 为 succeeded 时取 resultUrl

认证方式

API Key（公开接口）

所有公开接口需要在请求头带上 API Key：

Authorization: Bearer sk_live_xxxxxxxxxxxxxx

公开接口

使用 API Key 认证

POST/api/video/submitAPI Key

提交视频生成任务

请求体

{
  "provider": "kling",          // 可选，指定 Provider；省略则自动选择
  "prompt": "一只猫在草地上奔跑",
  "user_identifier": "user_123" // 可选，用于用量统计
}

响应体

{
  "success": true,
  "data": {
    "jobId": "job_abc123"
  }
}

curl 示例

curl -X POST https://your-hub.com/api/video/submit \
  -H "Authorization: Bearer sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一只猫在草地上奔跑","user_identifier":"u1"}'
GET/api/video/status?jobId=xxxAPI Key

查询任务状态与结果

响应体

{
  "success": true,
  "data": {
    "status": "succeeded",
    "progress": 100,
    "resultUrl": "https://..."
  }
}

curl 示例

curl "https://your-hub.com/api/video/status?jobId=job_abc123" \
  -H "Authorization: Bearer sk_live_xxxxxx"
GET/api/relay/v1/modelsAPI Key

列出可用模型（OpenAI 兼容）

curl 示例

curl "https://your-hub.com/api/relay/v1/models" \
  -H "Authorization: Bearer sk_live_xxxxxx"
POST/api/relay/v1/chat/completionsAPI Key

聊天补全（OpenAI 兼容）

请求体

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7
}

curl 示例

curl -X POST https://your-hub.com/api/relay/v1/chat/completions \
  -H "Authorization: Bearer sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"你好"}]}'
POST/api/relay/v1/images/generationsAPI Key

图片生成（OpenAI 兼容）

请求体

{
  "model": "dall-e-3",
  "prompt": "a cute cat sitting on a windowsill",
  "n": 1,
  "size": "1024x1024"
}

响应体

{
  "data": [
    {
      "url": "https://..."
    }
  ]
}

curl 示例

curl -X POST https://your-hub.com/api/relay/v1/images/generations \
  -H "Authorization: Bearer sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"dall-e-3","prompt":"a cute cat","n":1}'
POST/api/relay/v1/embeddingsAPI Key

文本嵌入（OpenAI 兼容）

请求体

{
  "model": "text-embedding-3-small",
  "input": "你好世界"
}

curl 示例

curl -X POST https://your-hub.com/api/relay/v1/embeddings \
  -H "Authorization: Bearer sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"你好世界"}'
GET/api/user/quotaAPI Key

查询当前用户配额余额

响应体

{
  "success": true,
  "data": {
    "totalQuota": 10000,
    "usedQuota": 3500,
    "remainingQuota": 6500
  }
}

curl 示例

curl "https://your-hub.com/api/user/quota" \
  -H "Authorization: Bearer sk_live_xxxxxx"
POST/api/user/redemptionAPI Key

使用兑换码充值配额

请求体

{
  "code": "REDEEM-XXXX-XXXX"
}

响应体

{
  "success": true,
  "data": {
    "addedQuota": 5000,
    "totalQuota": 15000
  }
}

curl 示例

curl -X POST https://your-hub.com/api/user/redemption \
  -H "Authorization: Bearer sk_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"code":"REDEEM-XXXX-XXXX"}'
GET/api/health无需认证

健康检查（无需认证）

响应体

{
  "status": "ok",
  "checks": {
    "db": "ok",
    "redis": "ok"
  }
}

curl 示例

curl https://your-hub.com/api/health

流式输出 (SSE)

聊天补全接口支持 SSE（Server-Sent Events）流式传输，设置 stream: true 即可。

JavaScript / TypeScript（fetch + ReadableStream）

const evtSource = new EventSource(
  'https://your-hub.com/api/relay/v1/chat/completions?' +
  new URLSearchParams({
    model: 'gpt-4',
    messages: JSON.stringify([
      { role: 'user', content: '你好' }
    ]),
    stream: 'true'
  }),
  { headers: { Authorization: 'Bearer sk_live_xxx' } }
);

// 注意：SSE 不支持自定义 Header，建议使用 fetch + ReadableStream 方式
const response = await fetch('/api/relay/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '你好' }],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value, { stream: true });
  // 解析 SSE 格式：data: {...}\n\n
  const lines = chunk.split('\n').filter(l => l.startsWith('data: '));
  for (const line of lines) {
    const data = line.slice(6);
    if (data === '[DONE]') return;
    const parsed = JSON.parse(data);
    const content = parsed.choices?.[0]?.delta?.content ?? '';
    process.stdout.write(content); // 打字机效果
  }
}

Python（openai SDK）

import openai

client = openai.OpenAI(
    api_key="sk_live_xxx",
    base_url="https://your-hub.com/api/relay/v1"
)

# 流式输出
stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "你好"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)  # 打字机效果

说明

  • •流式响应格式完全兼容 OpenAI SSE 格式（data: {...}）
  • •流结束时发送 data: [DONE]
  • •每个 chunk 中 choices[0].delta.content 包含增量文本
  • •建议使用 fetch + ReadableStream 而非原生 EventSource（后者不支持自定义 Header）

SDK 下载

基于 OpenAI SDK 封装，零成本迁移。

Py
Python SDK

安装

pip install openai

使用

import openai

client = openai.OpenAI(
    api_key="sk_live_xxxxxxxxxxxx",
    base_url="https://your-hub.com/api/relay/v1"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)
JS
Node.js SDK

安装

npm install openai

使用

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk_live_xxxxxxxxxxxx',
  baseURL: 'https://your-hub.com/api/relay/v1',
});

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

错误码

HTTP 状态码说明
200请求成功
400请求参数错误，见 message 字段
401未认证或 Token 无效/过期
403无权限（Key 已吊销、超额度等）
429请求频率超限
500服务器内部错误