st-ai 通用接口文档

📖 概述

st-ai 是一个新一代大模型网关与AI资产管理系统，提供统一的API接口来访问多种AI模型服务。本文档介绍了面向最终用户的主要API接口调用方法。

支持的功能：

• 💬 聊天对话（支持多模态：文本、图片、音频、视频）
• 🎨 AI图像生成
• 🎬 AI视频生成

基础信息：

• 基础URL：https://api.sora2.pub
• 请求格式：JSON
• 响应格式：JSON
• 字符编码：UTF-8

---

🔑 认证方式

所有API请求都需要在HTTP请求头中携带认证信息：

Authorization: Bearer YOUR_API_TOKEN

示例：

curl https://api.sora2.pub/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

---

📋 接口列表

快速导航

1. 聊天补全接口 - 对话和多模态对话
2. 图像生成接口 - AI绘画
3. 视频生成接口 - AI视频创作

---

1. 聊天补全接口（Chat Completions）

接口地址： POST /v1/chat/completions

功能说明： 发送对话消息，获取AI模型的回复

请求参数：

参数名	类型	必填	说明
model	string	是	模型名称，如 gpt-4、gpt-3.5-turbo
messages	array	是	对话消息列表
temperature	float	否	生成温度，0-2之间，默认1
max_tokens	integer	否	最大生成token数
stream	boolean	否	是否流式返回，默认false
top_p	float	否	核采样参数，0-1之间
frequency_penalty	float	否	频率惩罚，-2.0到2.0之间
presence_penalty	float	否	存在惩罚，-2.0到2.0之间
tools	array	否	可用的工具列表
tool_choice	string/object	否	工具选择策略

messages 结构：

{
  "role": "user",     // 角色：system/user/assistant
  "content": "你好"   // 消息内容（支持文本或多模态内容）
}

请求示例（普通对话）：

curl https://api.sora2.pub/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "你是一个有帮助的助手。"
      },
      {
        "role": "user",
        "content": "什么是人工智能？"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

请求示例（多模态 - 图片）：

curl https://api.sora2.pub/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4-vision-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "这张图片里有什么？"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg",
              "detail": "high"
            }
          }
        ]
      }
    ]
  }'

响应示例（非流式）：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能（AI）是计算机科学的一个分支..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  }
}

流式响应示例：

# 设置 stream: true
curl https://api.sora2.pub/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

流式返回格式（Server-Sent Events）：

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: [DONE]

---

2. 图像生成接口

接口地址： POST /v1/images/generations

功能说明： 根据文本提示生成图像

请求参数：

参数名	类型	必填	说明
model	string	否	模型名称，如 dall-e-3
prompt	string	是	图像描述文本
n	integer	否	生成图片数量，默认1
size	string	否	图片尺寸，如 1024x1024、1792x1024
quality	string	否	图片质量：standard 或 hd
response_format	string	否	返回格式：url 或 b64_json
style	string	否	图片风格：vivid 或 natural

请求示例：

curl https://api.sora2.pub/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只戴着墨镜的猫在海滩上冲浪",
    "n": 1,
    "size": "1024x1024",
    "quality": "hd"
  }'

响应示例：

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "revised_prompt": "A cat wearing sunglasses surfing on a beach..."
    }
  ]
}

---

3. 视频生成接口

接口地址： POST /v1/videos

功能说明： 根据文本或图片生成视频（支持多种视频生成模型）

请求参数：

参数名	类型	必填	说明
model	string	否	模型名称，如 kling-v1、runway-gen3
prompt	string	是	视频描述文本
image	string	否	图片URL或Base64（用于图生视频）
duration	float	否	视频时长（秒），如 5.0
width	integer	否	视频宽度，如 512
height	integer	否	视频高度，如 512
fps	integer	否	帧率，如 30
seed	integer	否	随机种子
n	integer	否	生成视频数量，默认1
response_format	string	否	响应格式：url
metadata	object	否	供应商特定参数（如负面提示词、风格等）

请求示例（文本生成视频）：

curl https://api.sora2.pub/v1/videos \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v1",
    "prompt": "一名宇航员在月球表面漫步，地球在背景中升起",
    "duration": 5.0,
    "width": 1280,
    "height": 720,
    "fps": 30
  }'

请求示例（图片生成视频）：

curl https://api.sora2.pub/v1/videos \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v1",
    "prompt": "让图片中的人物动起来",
    "image": "https://example.com/image.jpg",
    "duration": 5.0
  }'

响应示例：

{
  "task_id": "abcd1234efgh",
  "status": "queued"
}

获取视频任务状态： GET /v1/videos/{task_id}

curl https://api.sora2.pub/v1/videos/abcd1234efgh \
  -H "Authorization: Bearer YOUR_API_TOKEN"

任务状态响应示例：

任务进行中：

{
  "id": "abcd1234efgh",
  "object": "video",
  "model": "kling-v1",
  "status": "in_progress",
  "progress": 65,
  "created_at": 1677652288
}

任务完成：

{
  "id": "abcd1234efgh",
  "object": "video",
  "model": "kling-v1",
  "status": "completed",
  "progress": 100,
  "created_at": 1677652288,
  "completed_at": 1677652388,
  "metadata": {
    "duration": 5.0,
    "fps": 30,
    "width": 1280,
    "height": 720
  }
}

获取视频内容： GET /v1/videos/{task_id}/content

curl https://api.sora2.pub/v1/videos/abcd1234efgh/content \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --output video.mp4

任务状态说明：

• queued - 任务排队中
• in_progress - 任务执行中
• completed - 任务已完成
• failed - 任务失败

完整使用示例（Python）：

import requests
import time

API_BASE = "https://api.sora2.pub"
API_TOKEN = "YOUR_API_TOKEN"
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# 1. 提交视频生成任务
response = requests.post(f"{API_BASE}/v1/videos", 
    headers=headers,
    json={
        "model": "kling-v1",
        "prompt": "一只可爱的小猫在玩毛线球",
        "duration": 5.0,
        "width": 1280,
        "height": 720
    }
)
task_id = response.json()["task_id"]
print(f"任务已提交，ID: {task_id}")

# 2. 轮询任务状态
while True:
    response = requests.get(f"{API_BASE}/v1/videos/{task_id}", headers=headers)
    data = response.json()
    status = data["status"]
    progress = data.get("progress", 0)
    
    print(f"任务状态: {status}, 进度: {progress}%")
    
    if status == "completed":
        print("任务完成！")
        break
    elif status == "failed":
        print(f"任务失败: {data.get('error', {}).get('message', '未知错误')}")
        break
    
    time.sleep(3)  # 每3秒查询一次

# 3. 下载视频
response = requests.get(f"{API_BASE}/v1/videos/{task_id}/content", headers=headers)
with open("output_video.mp4", "wb") as f:
    f.write(response.content)
print("视频已下载到 output_video.mp4")

---

📊 响应状态码

状态码	说明
200	请求成功
400	请求参数错误
401	认证失败，Token无效
403	权限不足
429	请求过于频繁，触发限流
500	服务器内部错误
502	上游服务错误
503	服务暂时不可用

---

⚠️ 错误响应格式

{
  "error": {
    "message": "错误描述信息",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

---

💡 使用建议

1. Token管理：妥善保管API Token，不要在客户端代码中硬编码
2. 错误处理：建议实现重试机制，处理临时性错误
3. 流式响应：对于长文本生成，建议使用流式响应以提升用户体验
4. 速率限制：注意遵守API调用频率限制，避免触发限流
5. 成本控制：合理设置max_tokens参数，控制使用成本
6. 异步任务：
   • 视频生成、图像生成（MJ）、音乐生成等为异步任务
   • 提交后会返回task_id，需要轮询查询任务状态
   • 建议每3-5秒查询一次任务状态，避免过于频繁
   • 任务完成后及时下载结果，部分平台会定期清理历史文件
7. 多模态输入：
   • 图片URL需要确保可访问，建议使用HTTPS
   • 支持Base64编码，但注意大小限制（通常<10MB）
   • 视频生成时，图片分辨率会影响生成质量和速度

---

最后更新： 2025-10-23