视频生成 API 文档

概览

完整调用流程：

上传素材文件

上传图片、音频或视频，返回的 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?..."
}

文件类型与限制

创建视频生成任务

获取可用模型

curl https://api.sudashuiapi.com/v1/models \
  -H "Authorization: Bearer 你的_API_Key"

官方模型：模型名以 sdas-gf- 开头时属于官方模型，支持真人素材库。使用真人或虚拟人像图片时，需要通过 officialAssetIndexes 标记对应图片。

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

基础参数

metadata.payload 参数

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

参数规则

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

官方模型真人素材

图片仍然先通过文件上传接口上传到 R2，然后把返回的 URL 放入 imageUrls、firstFrameUrl 或 lastFrameUrl。系统只会登记 officialAssetIndexes 标记的图片；动漫、插画、背景图等不需要登记的图片不要标记。

• references 模式：下标直接对应 imageUrls。例如 imageUrls[1] 对应 officialAssetIndexes: [1]，在 prompt 中是 @image2。
• frames 模式：firstFrameUrl 的下标是 0，lastFrameUrl 的下标是 1。
• 多个真人图可以同时标记，例如 officialAssetIndexes: [0, 2]。
• 下标不能重复、不能超出图片范围。素材登记失败时，任务不会降级为普通 URL 提交。
• sdas-gf- 官方模型当前不支持 videoUrls，传入视频参考会返回参数错误。

示例：第一张是普通动漫背景，第二张是真人图，因此只标记下标 1：

{
  "model": "sdas-gf-seedance-2.0-fast-720p",
  "prompt": "让 @image2 中的人物出现在 @image1 的动漫场景中，自然看向镜头",
  "duration": 5,
  "metadata": {
    "payload": "{\"aspectRatio\":\"16:9\",\"mode\":\"references\",\"imageUrls\":[\"https://files.sudashuiapi.com/proxy/xxx/anime-background.jpg\",\"https://files.sudashuiapi.com/proxy/xxx/person.jpg\"],\"officialAssetIndexes\":[1]}"
  }
}

素材顺序对应

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

生成任务素材限制

创建任务响应

创建成功响应

创建成功后会返回任务对象。请保存 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);

{
  "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\"]}"
  }
}

{
  "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\"]}"
  }
}

{
  "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\"]}"
  }
}

{
  "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\"]}"
  }
}

{
  "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\"]}"
  }
}

{
  "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\"}"
  }
}

查询任务

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);

状态说明

成功示例

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

常见错误原因