API Reference

视频生成 API 文档

上传素材文件，通过统一的视频接口创建生成任务、查询任务状态，并查看请求参数、响应结构、状态含义和错误示例。

重要提醒：模型请求方式统一通用，但是各个模型时长、素材数量、支持比例等参数需要以模型广场上的模型说明为准。上传素材和通过统一视频接口创建任务都需要携带 Authorization: Bearer <API Key>；创建视频任务使用 metadata.payload。

概览

完整调用流程：

1. 上传素材POST https://files.sudashuiapi.com
返回素材 URL 和文件元数据。
2. 创建任务POST /v1/video/generations
提交文生视频或参考素材生视频任务。
3. 查询任务GET /v1/video/generations/{task_id}
轮询任务状态和结果。
4. 获取结果data.result_url 或 creations[0].url
成功后拿到视频地址。

上传素材文件

POSThttps://files.sudashuiapi.com

上传图片、音频或视频。响应中的 url 可用于 imageUrls、audioUrls、videoUrls、firstFrameUrl 或 lastFrameUrl；其余字段用于描述已上传文件。

curl --location 'https://files.sudashuiapi.com' \
  -H 'Authorization: Bearer 你的_API_Key' \
  --form 'file=@"/D:/Users/24553/Pictures/004.jpg"'
const form = new FormData();
form.append("file", fileInput.files[0]);

const response = await fetch("https://files.sudashuiapi.com", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 你的_API_Key"
  },
  body: form
});
const data = await response.json();
import requests

with open(r"D:/Users/24553/Pictures/004.jpg", "rb") as f:
    response = requests.post(
        "https://files.sudashuiapi.com",
        headers={"Authorization": "Bearer 你的_API_Key"},
        files={"file": f},
    )
print(response.json())
<?php
$ch = curl_init("https://files.sudashuiapi.com");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer 你的_API_Key"],
  CURLOPT_POSTFIELDS => [
    "file" => new CURLFile("D:/Users/24553/Pictures/004.jpg")
  ]
]);
echo curl_exec($ch);
{
  "url": "https://files.sudashuiapi.com/proxy/uploads/20260826/1787710210571-665e406a-2c82-4753-b0bc-9c4a0b0d2b31-03e6015fdd3ab97aa764f5221799d69a.png",
  "key": "uploads/20260826/1787710210571-665e406a-2c82-4753-b0bc-9c4a0b0d2b31-03e6015fdd3ab97aa764f5221799d69a.png",
  "size": 899870,
  "contentType": "image/png",
  "expiresAt": "2026-08-26T04:10:10.571Z"
}
字段类型说明
urlstring素材访问 URL，创建视频任务时放入对应的素材字段。
keystring素材在文件存储中的对象键，一般无需在视频请求中传入。
sizeinteger文件大小，单位为字节。
contentTypestring文件 MIME 类型，例如 image/png。
expiresAtstring响应中的时间字段，使用 ISO 8601 格式。

文件类型与限制

类型MIME Type扩展名上传大小
图片image/jpeg.jpeg, .jpg单张小于 30 MB
图片image/png.png单张小于 30 MB
图片image/webp.webp单张小于 30 MB
视频video/mp4.mp4单个小于 50 MB
视频video/quicktime.mov单个小于 50 MB
音频audio/mpeg.mp3单个小于 15 MB
音频audio/wav.wav单个小于 15 MB

创建视频生成任务

POSThttps://api.sudashuiapi.com/v1/video/generations

获取可用模型

可用模型和模型能力会持续更新。本页面不固定展示模型列表，请通过模型接口或模型广场查看最新可用模型及详细参数。
通过 API 获取GET https://api.sudashuiapi.com/v1/models
返回当前 API Key 可使用的模型。
通过模型广场查看https://www.sudashuiapi.com/pricing
查看最新模型、价格和单模型参数说明。
curl https://api.sudashuiapi.com/v1/models \
  -H "Authorization: Bearer 你的_API_Key"

不要额外传 resolution，分辨率由模型名决定。

基础参数

字段类型必填说明
modelstring是必须是 /v1/models 或模型广场中当前可用的模型名，分辨率由模型名决定。
promptstring建议填写提示词，支持 @image1、@audio1、@video1 等引用。
durationnumber是通用文档范围为 4 到 15 秒；具体可用时长以模型广场中的单模型说明为准。
metadata.payloadstring是JSON 字符串，不能直接传 JSON 对象。
不要在外层传 images、imageUrls、videoUrls、audioUrls、firstFrameUrl、lastFrameUrl、aspectRatio、mode、resolution。

metadata.payload 参数

metadata.payload 是一个 JSON 字符串。它内部的 JSON 对象支持以下字段：

字段类型必填说明
aspectRatiostring是画面比例
modestring是生成模式：references 或 frames
imageUrlsstring[]否图片 URL 数组，references 模式使用；可用数量以模型广场中的模型说明为准
videoUrlsstring[]否视频 URL 数组，references 模式使用；可用数量以模型广场中的模型说明为准
audioUrlsstring[]否音频 URL 数组，references 模式使用；可用数量以模型广场中的模型说明为准
firstFrameUrlstring条件必填首帧图片 URL，frames 模式必填
lastFrameUrlstring条件必填尾帧图片 URL，frames 模式必填
不同模型支持的时长、参考图片、参考视频、参考音频数量可能不同。下表保留通用调用范围，实际请求请根据模型广场中的模型说明调整。
aspectRatio 可选值1:1 3:4 4:3 9:16 16:9 21:9 adaptive
mode 可选值references frames

参数规则

  • mode=references：用于文生视频、图片参考、视频参考、音频参考，以及多素材组合参考。
  • mode=frames：用于首尾帧视频。
  • mode=frames 时必须传 firstFrameUrl 和 lastFrameUrl。
  • mode=frames 时不能传 imageUrls、videoUrls、audioUrls。
  • mode=references 时不能传 firstFrameUrl、lastFrameUrl。
  • metadata.payload 内不能传 model、resolution、duration、prompt。

素材顺序对应

数组字段数组位置prompt 引用
imageUrlsimageUrls[0] / imageUrls[1]@image1 / @image2
audioUrlsaudioUrls[0] / audioUrls[1]@audio1 / @audio2
videoUrlsvideoUrls[0] / videoUrls[1]@video1 / @video2

@image1 对应第一张图片，不是文件名中的数字。图片、音频、视频的编号互不影响。

生成任务素材限制

素材类型数量限制大小限制时长限制其他限制
图片以模型广场说明为准单张小于 30 MB-支持 jpg / jpeg / png / webp
音频以模型广场说明为准单个小于 15 MB以模型广场说明为准支持 mp3 / wav
视频以模型广场说明为准单个小于 50 MB以模型广场说明为准像素和格式要求以模型广场说明为准
imageUrls、audioUrls、videoUrls 的可用数量由具体模型决定，请以模型广场上对应模型的详细说明为准。

创建任务响应

创建成功响应

创建成功后会返回任务对象。请保存 task_id，用于后续查询。

{
  "id": "task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN",
  "task_id": "task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN",
  "object": "video",
  "model": "sd-api-2-fast-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1780990464
}

创建失败响应

参数不合法、鉴权失败或其他请求错误时，会返回失败响应。常见参数错误示例：

{
  "code": "fail_to_fetch_task",
  "message": "{\"state\":\"failed\",\"err_code\":\"invalid_request\",\"message\":\"duration must be from 4 to 15 seconds.\",\"creations\":[]}",
  "data": null
}

创建任务场景示例

文生视频

无素材
curl https://api.sudashuiapi.com/v1/video/generations \
  -H "Authorization: Bearer 你的_API_Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd-api-2-fast-720p",
    "prompt": "一只可爱的小猫，电影感镜头",
    "duration": 4,
    "metadata": {
      "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\"}"
    }
  }'
const response = await fetch("https://api.sudashuiapi.com/v1/video/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 你的_API_Key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "sd-api-2-fast-720p",
    prompt: "一只可爱的小猫，电影感镜头",
    duration: 4,
    metadata: {
      payload: JSON.stringify({ aspectRatio: "16:9", mode: "references" })
    }
  })
});
const data = await response.json();
import json
import requests

response = requests.post(
    "https://api.sudashuiapi.com/v1/video/generations",
    headers={
        "Authorization": "Bearer 你的_API_Key",
        "Content-Type": "application/json",
    },
    json={
        "model": "sd-api-2-fast-720p",
        "prompt": "一只可爱的小猫，电影感镜头",
        "duration": 4,
        "metadata": {
            "payload": json.dumps({"aspectRatio": "16:9", "mode": "references"})
        },
    },
)
print(response.json())
<?php
$payload = [
  "model" => "sd-api-2-fast-720p",
  "prompt" => "一只可爱的小猫，电影感镜头",
  "duration" => 4,
  "metadata" => [
    "payload" => json_encode(["aspectRatio" => "16:9", "mode" => "references"])
  ]
];

$ch = curl_init("https://api.sudashuiapi.com/v1/video/generations");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer 你的_API_Key",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE)
]);
echo curl_exec($ch);

单图参考生视频

@image1
{
  "model": "sd-api-2-fast-720p",
  "prompt": "让 @image1 里的小猫动起来，电影感镜头",
  "duration": 4,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/cat.jpg\"]}"
  }
}

多图参考生视频

@image1 + @image2
{
  "model": "sd-api-2-fast-720p",
  "prompt": "让 @image1 里的角色进入 @image2 的场景中，自然运镜，电影感镜头",
  "duration": 4,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/character.jpg\",\"https://files.sudashuiapi.com/proxy/xxx/scene.jpg\"]}"
  }
}

图片 + 音频参考

@image1 + @audio1
{
  "model": "sd-api-2-fast-720p",
  "prompt": "让 @image1 里的角色跟着 @audio1 的节奏做动作",
  "duration": 4,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/character.jpg\"],\"audioUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/music.mp3\"]}"
  }
}

视频参考

@video1
{
  "model": "sd-api-2-fast-720p",
  "prompt": "参考 @video1 的动作，把主体变成可爱小猫，动画风格",
  "duration": 4,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"videoUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/reference.mp4\"]}"
  }
}

图片 + 视频 + 音频参考

@image1 + @video1 + @audio1
{
  "model": "sd-api-2-fast-720p",
  "prompt": "让 @image1 里的角色参考 @video1 的动作，并跟随 @audio1 的节奏，生成电影感视频",
  "duration": 4,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/character.jpg\"],\"videoUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/action.mp4\"],\"audioUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/music.mp3\"]}"
  }
}

多图 + 多音频 + 多视频参考

多素材组合
{
  "model": "sd-api-2-fast-720p",
  "prompt": "让 @image1 的角色在 @image2 的场景中，参考 @video1 的动作，配合 @audio1 的节奏，结尾参考 @video2 的镜头运动",
  "duration": 6,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/character.jpg\",\"https://files.sudashuiapi.com/proxy/xxx/scene.jpg\"],\"videoUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/action.mp4\",\"https://files.sudashuiapi.com/proxy/xxx/camera.mp4\"],\"audioUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/music.mp3\",\"https://files.sudashuiapi.com/proxy/xxx/effect.wav\"]}"
  }
}

首尾帧生成视频

frames

首尾帧模式使用 firstFrameUrl 和 lastFrameUrl，不要再传 imageUrls。

{
  "model": "sd-2-1080p",
  "prompt": "从第一张图自然过渡到第二张图，电影感镜头",
  "duration": 6,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"frames\",\"firstFrameUrl\":\"https://files.sudashuiapi.com/proxy/xxx/first.jpg\",\"lastFrameUrl\":\"https://files.sudashuiapi.com/proxy/xxx/last.jpg\"}"
  }
}

查询任务

GEThttps://api.sudashuiapi.com/v1/video/generations/{task_id}
curl https://api.sudashuiapi.com/v1/video/generations/task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN \
  -H "Authorization: Bearer 你的_API_Key"
const response = await fetch(
  "https://api.sudashuiapi.com/v1/video/generations/task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN",
  { headers: { "Authorization": "Bearer 你的_API_Key" } }
);
const data = await response.json();
import requests

response = requests.get(
    "https://api.sudashuiapi.com/v1/video/generations/task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN",
    headers={"Authorization": "Bearer 你的_API_Key"},
)
print(response.json())
<?php
$ch = curl_init("https://api.sudashuiapi.com/v1/video/generations/task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer 你的_API_Key"]
]);
echo curl_exec($ch);

状态说明

外层状态内层 state含义
SUBMITTEDqueueing已提交，排队中
IN_PROGRESSprocessing生成中
SUCCESSsuccess生成成功
FAILUREfailed生成失败

成功示例

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_DrwbCgmERlqqvftqyf2o59FaWynwJPDN",
    "status": "SUCCESS",
    "result_url": "https://files.sudashuiapi.com/proxy/generating/output.mp4",
    "progress": "100%",
    "data": {
      "state": "success",
      "message": "",
      "err_code": "",
      "creations": [
        {
          "id": "6a27c2007f67cc1d1c5bdcc7",
          "url": "https://files.sudashuiapi.com/proxy/generating/output.mp4",
          "cover_url": "https://files.sudashuiapi.com/proxy/generating/first.jpg"
        }
      ]
    }
  }
}

失败示例

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_mDlJcHGjpem3n6aR4I0DeiYMOqvtWAA6",
    "status": "FAILURE",
    "fail_reason": "Real human faces are not supported.",
    "result_url": "Real human faces are not supported.",
    "progress": "100%",
    "data": {
      "state": "failed",
      "message": "Real human faces are not supported.",
      "err_code": "Real human faces are not supported.",
      "creations": []
    }
  }
}

错误响应

参数错误

{
  "code": "fail_to_fetch_task",
  "message": "{\"state\":\"failed\",\"err_code\":\"invalid_request\",\"message\":\"duration must be from 4 to 15 seconds.\",\"creations\":[]}",
  "data": null
}

常见错误原因

错误原因说明
duration must be from 4 to 15 seconds时长不在 4-15 秒范围内。
metadata.payload.aspectRatio must be one of...画面比例不合法。
metadata.payload.mode must be one of...生成模式不合法。
Do not pass top-level images...媒体参数不能放外层。
unauthorized缺少或使用了无效 API Key。

© 视频生成 API 文档