StarFrame API

概述

StarFrame API 是面向创作者与应用开发者的视频生成服务，用统一、稳定、易接入的 API，把文本、图片与首尾帧素材快速转化为视频内容。

项目 值
Base URL https://api.xzapi.vip
用户工作台 https://web.xzapi.vip

快速开始

创建 API 密钥，提交生成请求，然后使用任务 ID 查询结果并下载视频。

01创建密钥

在控制台生成 API Key，妥善保存在服务端环境变量中。

02提交请求

选择模型，传入提示词、画幅、时长和参考素材。

03获取结果

轮询任务状态，完成后通过统一 content 地址读取视频文件。

新手操作图文指南请查看 快速开始。

鉴权与请求头

所有 API 请求使用 Bearer Token。API Key 仅应保存在服务端，不要写入浏览器代码、公开仓库或日志。

请求头 值 说明
Authorization Bearer 你的_API_KEY 必填，用于识别账户和调用权限
Content-Type application/json JSON 请求必填 
Authorization: Bearer 你的_API_KEY
Content-Type: application/json

接口端点

所有模型系列共用以下三个端点：

POST/v1/videos创建视频生成任务
GET/v1/videos/:taskId查询任务状态、进度和结果
GET/v1/videos/:taskId/content下载已完成任务的视频文件

通用请求参数

创建任务时使用以下参数，具体约束（如 prompt 长度、可选值）因模型系列而异，见下方各系列说明。

参数 类型 必填 说明
model string 是 模型名称，见各系列模型列表
prompt string 是 视频内容描述，长度限制因模型而异
mode string 是 references / frames（默认仅 references)
aspect_ratio string 否 画面比例，范围因模型而异
duration number 否 视频时长（秒），范围因模型而异
resolution string 否 分辨率，范围因模型而异
references object 否 参考素材块，留空即为纯文生视频
frames object 条件 mode=frames 时必填
client_task_id string 是 幂等任务 ID，最长 128 字符，仅支持字母、数字、下划线、连字符和点号
mode 互斥：references 不能带 frames，frames 不能带 references。

references 结构

参考素材放在 references 对象内，当前仅支持公网可访问的 URL，不支持 multipart/form-data 文件上传，也不接收 base64 / data URL。

{
  "references": {
    "image": "https://example.com/ref.jpg",
    "images": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"],
    "video": "https://example.com/ref.mp4",
    "videos": ["https://example.com/ref1.mp4", "https://example.com/ref2.mp4"],
    "audio": "https://example.com/ref.mp3",
    "audios": ["https://example.com/ref1.mp3", "https://example.com/ref2.mp3"]
  }
}
字段 类型 说明
image string 单张参考图（1 张时用此字段）
images string[] 多张参考图（≥2 张时用此字段）
video string 单个参考视频（1 条时用此字段）
videos string[] 多个参考视频（≥2 条时用此字段）
audio string 单个参考音频（1 条时用此字段）
audios string[] 多个参考音频（≥2 条时用此字段）
  • image/images 互斥，video/videos 互斥，audio/audios 互斥
  • 只有 1 个元素必须用单数，≥2 个才能用复数；空数组、单元素数组均返回 400

frames 结构

首尾帧驱动模式，需将 mode 设为 frames。仅 CH04 和 CH06 系列支持此模式。

{
  "frames": {
    "first_frame": "https://example.com/start.jpg",
    "last_frame": "https://example.com/end.jpg"
  }
}
字段 类型 必填 说明
first_frame string 是 首帧图片 URL
last_frame string 是 尾帧图片 URL

响应格式

创建任务响应

{
  "id": "task_abc123def456",
  "object": "video",
  "model": "ch1-sd-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1717497600
}

查询任务响应

完成状态：

{
  "id": "task_abc123def456",
  "object": "video",
  "model": "ch1-sd-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1717497600,
  "completed_at": 1717497700,
  "metadata": {
    "url": "/v1/videos/task_abc123def456/content"
  }
}

失败状态：

{
  "id": "task_abc123def456",
  "object": "video",
  "model": "ch1-sd-2.0",
  "status": "failed",
  "progress": 100,
  "created_at": 1717497600,
  "completed_at": 1717497700,
  "metadata": {
    "fail_reason": "video generation failed"
  }
}

响应字段说明

字段 类型 出现时机 说明
id string 始终 任务唯一标识
object string 始终 固定值 "video"
model string 始终 使用的模型名
status string 始终 任务状态，见下方任务状态说明
progress number 始终 进度百分比 0-100
created_at number 始终 创建时间戳（Unix 秒）
completed_at number completed/failed 完成/失败时间戳
metadata.url string completed 视频下载路径（相对路径，拼接 Base URL 后 GET 获取）
metadata.fail_reason string failed 失败原因

错误响应

{
  "error": {
    "code": "invalid_params",
    "message": "具体错误描述"
  }
}

任务状态

状态 说明
queued 任务已创建，等待处理
in_progress 任务正在处理中
completed 任务完成，通过 GET /v1/videos/:taskId/content 下载视频
failed 任务失败，metadata.fail_reason 含失败原因
unknown 未知状态

client_task_id 幂等说明

每次创建任务都必须传入 client_task_id，建议使用你业务系统里的唯一订单号。

场景 建议
首次创建任务 使用新的 client_task_id
请求超时 使用同一个 client_task_id 重试，避免同一业务订单生成新任务
视频取回失败 使用同一个 client_task_id 重新提交，系统会继续尝试取回同一任务结果
新业务订单 使用新的 client_task_id
不要为同一笔业务订单随机更换 client_task_id。进行中或已完成时重复提交，请求会被拒绝，请使用原 task_id 查询任务。

代码示例

创建任务

curl -X POST https://api.xzapi.vip/v1/videos \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ch0101-sd-2.0",
    "prompt": "人物向前走，背景流动变换",
    "client_task_id": "order_20260724_000001",
    "mode": "references",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

查询任务状态

curl https://api.xzapi.vip/v1/videos/task_abc123def456 \
  -H "Authorization: Bearer 你的_API_KEY"

下载视频

curl -o output.mp4 https://api.xzapi.vip/v1/videos/task_abc123def456/content \
  -H "Authorization: Bearer 你的_API_KEY"

Python 完整轮询示例

import time
import requests

BASE = "https://api.xzapi.vip"
HEADERS = {"Authorization": "Bearer sk-xxxxxxxxxxxxxxxx", "Content-Type": "application/json"}
CLIENT_TASK_ID = "order_20260724_000001"

# 1. 创建任务
resp = requests.post(f"{BASE}/v1/videos", headers=HEADERS, json={
    "model": "ch0101-sd-2.0",
    "prompt": "人物向前走，背景流动变换",
    "client_task_id": CLIENT_TASK_ID,
    "mode": "references",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
}, timeout=120)

task_id = resp.json()["id"]
print(f"任务已创建：{task_id}")

# 2. 轮询任务状态
while True:
    task = requests.get(f"{BASE}/v1/videos/{task_id}", headers=HEADERS).json()
    status = task["status"]
    print(f"状态: {status} ({task['progress']}%)")
    if status in ("completed", "failed"):
        break
    time.sleep(5)

# 3. 下载视频
if task["status"] == "completed":
    video = requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=HEADERS).content
    with open("output.mp4", "wb") as f:
        f.write(video)
else:
    print(f"失败: {task.get('metadata', {}).get('fail_reason', '未知原因')}")