视频生成 API 文档

概览

完整调用流程：

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/1781054530419/1781054530419-004.jpg?..."
}

文件类型与限制

类型	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

模型列表

模型名	分辨率	说明
`sd-2-720p`	720p	标准2.0模型 720p
`sd-2-1080p`	1080p	标准2.0模型 1080p
`sd-api-2-720p`	720p	用于绕过人脸的2.0模型 720p
`sd-api-2-1080p`	1080p	用于绕过人脸的2.0模型 1080p
`sd-2-fast-720p`	720p	fast模型 720p
`sd-api-2-fast-720p`	720p	用于绕过人脸的fast模型 720p

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

基础参数

字段	类型	必填	说明
`model`	string	是	必须是模型列表中的模型名，分辨率由模型名决定。
`prompt`	string	建议填写	提示词，支持 `@image1`、`@audio1`、`@video1` 等引用。
`duration`	number	是	4 到 15 秒。
`metadata.payload`	string	是	JSON 字符串，不能直接传 JSON 对象。

不要在外层传 images、imageUrls、videoUrls、audioUrls、firstFrameUrl、lastFrameUrl、aspectRatio、mode、resolution。

metadata.payload 参数

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

字段	类型	必填	说明
`aspectRatio`	string	是	画面比例
`mode`	string	是	生成模式：`references` 或 `frames`
`imageUrls`	string[]	否	图片 URL 数组，`references` 模式使用，最多 9 张
`videoUrls`	string[]	否	视频 URL 数组，`references` 模式使用，最多 3 个
`audioUrls`	string[]	否	音频 URL 数组，`references` 模式使用，最多 3 个
`firstFrameUrl`	string	条件必填	首帧图片 URL，`frames` 模式必填
`lastFrameUrl`	string	条件必填	尾帧图片 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 引用
`imageUrls`	`imageUrls[0]` / `imageUrls[1]`	`@image1` / `@image2`
`audioUrls`	`audioUrls[0]` / `audioUrls[1]`	`@audio1` / `@audio2`
`videoUrls`	`videoUrls[0]` / `videoUrls[1]`	`@video1` / `@video2`

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

生成任务素材限制

素材类型	数量限制	大小限制	时长限制	其他限制
图片	最多 9 张	单张小于 30 MB	-	支持 jpg / jpeg / png / webp
音频	最多 3 个	单个小于 15 MB	总时长不超过 15 秒	支持 mp3 / wav
视频	最多 3 个	单个小于 50 MB	总时长 ≥ 2 秒且 ≤ 15 秒	像素总数范围：409600 到 927408，例如 640x640 到 834x1112

总素材数量限制：imageUrls、audioUrls、videoUrls 三个数组中的 URL 总数量必须小于等于 12。

创建任务响应

创建成功响应

创建成功后会返回任务对象。请保存 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	含义
`SUBMITTED`	`queueing`	已提交，排队中
`IN_PROGRESS`	`processing`	生成中
`SUCCESS`	`success`	生成成功
`FAILURE`	`failed`	生成失败

成功示例

{
  "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。