视频生成 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\"}"
  }
}

官方2请求文档

请求规则

• 所有请求都需要携带 Authorization: Bearer 你的_API_Key 和 Content-Type: application/json。
• metadata.payload 不适用于官方2原生请求；不要依赖其中的 officialAssetIndexes。
• 不要同时使用顶层 images 和 metadata.content[]，否则素材内容可能被替换。
• 官方2当前支持图片和音频素材，不支持任何视频参考，请勿传 video_url 或 @videoN。

模型与请求参数

素材上传与引用规则

先通过文件上传接口上传本地图片或音频，然后将返回的 HTTPS URL 原样放入 image_url.url 或 audio_url.url。

curl --location "https://files.sudashuiapi.com" \
  -H "Authorization: Bearer 你的_API_Key" \
  --form "file=@/path/to/person.jpg"

{
  "url": "https://files.sudashuiapi.com/proxy/uploads/20260720/example-person.jpg"
}

素材 URL 必须以 https://files.sudashuiapi.com 开头。不要传本地路径、Base64、file://、HTTP URL 或其他域名。

• 图片和音频分别独立编号，编号都从 1 开始。
• @imageN 对应 metadata.content[] 中第 N 个图片条目；@audioN 对应第 N 个音频条目。
• 图片和音频可以交叉排列，各自只按同类型条目的出现顺序编号。
• first_frame 和 last_frame 也属于图片，会占用图片编号。
• 建议固定使用小写 @imageN、@audioN。图生视频的首帧通常不需要在 prompt 中写 @image1。

content[0] = 图片 A  -> @image1
content[1] = 音频 A  -> @audio1
content[2] = 图片 B  -> @image2
content[3] = 音频 B  -> @audio2

官方2请求示例

以下示例均提交到 POST https://api.sudashuiapi.com/v1/video/generations。

{
  "model": "sdas-gf2-seedance-2.0-fast-720p",
  "prompt": "傍晚的海边城市，云层缓慢移动，镜头从街道平稳推进到海面，电影感光影",
  "seconds": "5",
  "metadata": {
    "ratio": "16:9",
    "watermark": false,
    "generate_audio": true
  }
}

{
  "model": "sdas-gf2-seedance-2.0-720p",
  "prompt": "人物自然抬头看向镜头，头发随风轻微摆动，镜头缓慢向前推进，保持人物身份和画面构图稳定",
  "seconds": "6",
  "metadata": {
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://files.sudashuiapi.com/proxy/uploads/person-start.jpg"
        }
      }
    ]
  }
}

{
  "model": "sdas-gf2-seedance-2.0-720p",
  "prompt": "让 @image1 中的人物穿着 @image2 中的服装，走进 @image3 的学校操场，人物身份和服装细节保持稳定，电影感跟拍镜头",
  "seconds": "8",
  "metadata": {
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/person.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/clothes.png" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/playground.jpg" }
      }
    ]
  }
}

{
  "model": "sdas-gf2-seedance-2.0-480p",
  "prompt": "让 @image1 和 @image2 中的人物走在 @image3 的学校操场上。@image2 使用 @audio1 的声音说大家好，背景动作节奏参考 @audio2，人物身份和口型保持自然",
  "seconds": "15",
  "metadata": {
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/person-1.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/person-2.png" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/playground.jpg" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/voice.mp3" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/rhythm.wav" }
      }
    ]
  }
}

{
  "model": "sdas-gf2-seedance-2.0-720p",
  "prompt": "镜头从第一帧自然过渡到最后一帧，人物动作连贯，场景结构稳定，避免突然切换",
  "seconds": "6",
  "metadata": {
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/first-frame.jpg" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://files.sudashuiapi.com/proxy/uploads/last-frame.jpg" }
      }
    ]
  }
}

官方2任务查询

提交成功后记录返回的 id 或 task_id：

{
  "id": "task_xxxxxxxxx",
  "task_id": "task_xxxxxxxxx",
  "status": "queued"
}

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

查询响应中的任务状态以 data.status 为准。

官方2查询成功响应

任务成功后，视频地址可从 data.result_url 或 data.data.content.video_url 获取；两个字段通常指向同一个已转存视频。

{
  "code": "success",
  "message": "",
  "data": {
    "id": 348856,
    "created_at": 1784554446,
    "updated_at": 1784554766,
    "task_id": "task_EVIaSjG5007TnefMIQhehPDWN0HzkK7T",
    "platform": "54",
    "user_id": 1,
    "group": "ssvip",
    "channel_id": 26,
    "quota": 6375000,
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://files.sudashuiapi.com/proxy/outputs/gf02/task_obbCpAqW0gl6vszvLxregnBqTTAAhrZu.mp4",
    "submit_time": 1784554446,
    "start_time": 1784554489,
    "finish_time": 1784554766,
    "progress": "100%",
    "properties": {
      "input": "",
      "upstream_model_name": "sdas-gf2-seedance-2.0-1080p",
      "origin_model_name": "sdas-gf2-seedance-2.0-1080p"
    },
    "data": {
      "id": "gf02:task_obbCpAqW0gl6vszvLxregnBqTTAAhrZu",
      "usage": {
        "total_tokens": 196425,
        "completion_tokens": 196425
      },
      "status": "succeeded",
      "content": {
        "video_url": "https://files.sudashuiapi.com/proxy/outputs/gf02/task_obbCpAqW0gl6vszvLxregnBqTTAAhrZu.mp4"
      }
    }
  }
}

官方2常见错误

查询任务

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
}

常见错误原因