如何使用 Seedance 2.5 API：快速上手指南

你可以用四步从 API key 走到成品 MP4： 发送一个已鉴权的 POST 请求，保存 request_id，每 10 到 20 秒 轮询一次结果端点，然后在链接过期前下载视频，通常在 24 小时 内。

如果我想要简短版，以下是我会牢记的要点：

• 使用正确的端点
  • seedance-2.5-text-to-video 用于文本提示词
  • seedance-2.5-image-to-video 用于为公开图片 URL 赋予动态
• 发送正确的请求头
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• 选择主要的输出设置
  • resolution：480p 到 4K
  • aspect_ratio：比如 16:9 或 9:16
  • duration：最长 16 秒
  • generate_audio：设为 true 以获得声音和口白
• 轮询而不是重复提交
  • 查询 predictions/{request_id}/result
  • 关注 queued、running、succeeded 或 failed
• 控制成本
  • 从 480p 或 720p 开始
  • 保持相同的 seed
  • 仅在镜头看起来正确时才以 1080p 或 4K 重跑

我还会留意最常见的失败点：鉴权头错误导致的 401、无额度导致的 402、活动任务过多导致的 429，以及 JSON 错误或字段缺失导致的 400。在 APIMart 上，额度在任务开始时被预留，仅在任务完成时才扣费；失败的任务会退款。

如果你在多个模型之间选择，Seedance 2.5 是这个阵容中的顶配选项：最长 16 秒、最高 3,840 × 2,160、最多 50 个参考输入。Seedance 2.0 处于中间档，而 Seedance 2 Mini 更适合低成本的草稿。

结论： 只要你能发出一个有效的 POST 请求并存下一个 ID，你就能跑通整个工作流。其余的就是提示词调优、耐心轮询，以及在 URL 超时前下载文件。对于后期处理，你可以用 AI 画布 来放大或编辑你生成的视频。

第 1 步：设置 APIMart 访问并为请求鉴权

每个 Seedance 2.5 请求都需要一个有效的 API key 和正确的请求头。从这里开始。一旦到位，你就可以进入视频生成的负载和任务追踪。

安全地创建和存储你的 API Key

在账户仪表盘的 Settings 或 API Keys 下创建你的 key。然后把它存在 .env 文件或环境变量中，而不是源代码管理里 ^[6][8]。

export APIMART_API_KEY="sk_live_xxxxxx"

如果 key 丢失，撤销它并重新创建一个 ^[3]。做集成测试时，使用单独的 sk_test_ key，这样就不会影响生产用量 ^[3]。

接下来，在每个请求中通过 Authorization 头包含那个 key。

正确添加 Authorization 头

向 https://muapi.ai/api/v1/ 发送请求，带上这些请求头：

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

一个小小的格式失误就能让请求失败。最常见的一个是漏掉 Bearer 前缀，或缺少 key 之前的空格 ^[3][7]。这通常会导致 401 Unauthorized 响应。漏掉 Content-Type: application/json 也可能让请求失败 ^[3][7]。

鉴权设置好之后，你就可以进入视频请求负载了。

第 2 步：构建一个 Seedance 2.5 视频生成请求

设置好 API key 后，下一步是构建一个有效的请求体。每个 Seedance 2.5 任务都以一个 POST 请求开始，发往两个端点之一，取决于你从什么开始。仅提示词生成用 https://muapi.ai/api/v1/seedance-2.5-text-to-video，为源图像赋予动态则用 https://muapi.ai/api/v1/seedance-2.5-image-to-video ^[1]。

选择正确的输入模式和参数

你的输入模式决定了负载的形状。文本生视频只需要一个 prompt。图像生视频还需要一个 image_url，指向一个可公开访问、小于 10 MB 的 JPG、PNG 或 WEBP 文件 ^[1]。

在此基础上，你通过几个主要字段控制输出：

• resolution：480p、720p、1080p 或 4K
• aspect_ratio：16:9、9:16、1:1、4:3、3:4 或 21:9
• duration：在 Muapi 上最长 16 秒
• generate_audio：一个布尔值，设为 true 时开启同步的环境声、音效和对白 ^[1]

一个聪明的做法是从 480p 加固定 seed 开始。如果运动、节奏和取景看起来正确，就用同一个 seed 在 1080p 或 4K 下再跑一次做最终版本。

对于提示词，使用这个流程：Subject → Action → Camera → Setting → Mood ^[4]。把运动、镜头方向和情绪放在 prompt 内部，在测试各变体时保持 seed 不变。如果你需要口型同步，把口白放在提示词字符串内部的双引号里。例如：she turns and says "We launch at dawn." 在这种情况下，确保 generate_audio 设为 true ^[1]。

一旦负载看起来没问题，提交任务并保存返回的 request ID。轮询时你会需要它。

cURL、Postman、Python 和 JavaScript 的示例请求

下面是同一个文本生视频负载在四种常用工具中的写法。

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - 创建一个新的 POST 请求，粘贴端点 URL，在 Headers 标签页添加 Authorization: Bearer <your_key> 和 Content-Type: application/json，然后把上面的 JSON 粘贴到 Body → raw → JSON。点击 Send 并从响应中保存 request_id。

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

有几个错误会让你很快栽跟头。不要发送一个无法公开访问的 image_url。不要在同一个提示词中堆叠相互冲突的镜头方向。而且在图像生视频模式下，如果源图像已经定义了主体，就不要再次描述它 ^[1]。

提交后，轮询任务状态，直到 MP4 URL 准备就绪。

何时在 APIMart 的视频模型阵容中使用 Seedance 2.5

这个快速对比帮你在开始调整提示词或提高分辨率之前挑好合适的模型。Seedance 2.5 给你原生 4K、最多 50 个参考输入和更长的视频支持。Seedance 2 Mini 更适合轻量草稿，而 Seedance 2.0 位居中间，是通用选项 ^[1][9][4]。

如果项目是最终交付物——比如产品发布视频、品牌化电影序列，或任何要送去播出的内容——Seedance 2.5 是更好的选择。对于需要高品質音声付きAI動画生成的项目，Google 的 Veo 3.1 是另一个有力竞争者。如果你还在测试创意，从 Mini 开始，以更低成本检查运动和锁定取景，然后再升到 2.5 做最终渲染。

第 3 步：提交任务、追踪状态并读取响应

一旦你发送了 POST 请求，API 会返回一个 request_id。保存它。你会用这个 ID 稍后检查任务，因为生成是异步运行的。

处理从创建到完成的异步任务

提交任务后，下一步很简单：轮询直到最终视频就绪。

向 https://muapi.ai/api/v1/predictions/{request_id}/result 发送一个 GET 请求。提交后先等约 10 秒再做第一次轮询，然后每 10–20 秒检查一次。如果你轮询得比每 5 秒一次还频繁，可能会触发速率限制 ^[1][3]。

每个响应都包含一个 status 字段。该字段告诉你正在发生什么以及你接下来应该做什么：

一旦任务达到 succeeded，在输出 URL 过期前抓取它。

读取输出字段并保存结果

当状态变为 succeeded 时，读取输出负载并存储结果。

成功的响应包含 video_url。如果你请求了，它可能还包含 last_frame_url。保存 video_url、可选的 last_frame_url，以及像 seed、duration、resolution、aspect_ratio 和 usage 这样的元数据。这些数据对计费和之后复现同一次运行都很重要 ^[11][13]。

输出 URL 通常在 24 小时内过期，所以要立即把文件下载到你自己的存储 ^[11][12][13]。如果一个任务失败，记录 error.code 和 error.message。而且如果失败与安全检查相关，不要自动重试 ^[2][11][12]。

第 4 步：排查错误、控制成本并收尾

修复鉴权、校验和速率限制错误

在你提交任务并轮询结果之后，几项简单的检查可以让生产运行不脱轨。大多数 Seedance 失败往往以同样的少数几种方式出现。

对于参考素材，确保 URL 是公开的，文件是 JPG、PNG 或 WEBP，并且保持在列出的大小限制之内 ^[12][4]。

削减成本并提升可靠性

错误处理设置好之后，下一步很简单：低成本测试，再大规模渲染。

从 480p 或 720p 开始你的提示词。这给你一种低成本的方式来检查取景、运动，以及提示词是否在做你想要的事。如果镜头看起来正确，用同一个 seed 值在 4K 下重跑，做最终输出 ^[1][4]。

视频长度也很重要。更短的视频成本更低，所以把 duration 保持在仍能完成任务的最小值 ^[1][10]。

还有一种团队烧钱的隐蔽方式：网络超时后的重复提交。一个干净的解决办法是在每次 POST 请求前对提示词、模型 ID 和媒体 URL 做哈希。如果那个哈希已经映射到某个任务 ID，就完全跳过新的提交 ^[11]。而且一旦任务达到 succeeded，把完成的文件保存到持久化存储，这样你就不必之后再依赖任务记录 ^[12][11]。

结论：从 API 文档到可用的视频生成

有了鉴权、负载、轮询和错误处理，你现在在 APIMart 上就拥有了一套完整的 Seedance 2.5 工作流。

常见问题

::: faq

Seedance 2.5 完成一个视频需要多久？

Seedance 2.5 可以生成一段最长 30 秒 的连续视频。不过，文档没有列出确切的完成时间。

该 API 异步运行。你提交一个任务，得到一个任务 ID，然后要么轮询状态端点，要么等待 webhook 来获取完成的视频。

处理时间会根据分辨率和场景复杂度等因素而变化。 :::

::: faq

如果我的视频 URL 在下载前就过期了怎么办？

如果你的视频 URL 在下载前就过期了，你将无法从那个链接获取文件。Seedance 让这些临时 URL 保持有效 24 小时。

安全的做法很简单：任务一显示为完成，就把视频复制到你自己的安全对象存储。因为 API 异步运行且不会永久保存输出，你的应用应该立即抓取视频并把它转移到长期存储。 :::

::: faq

重试失败请求时如何避免重复扣费？

使用与你自己的持久化任务记录绑定的幂等请求处理，而不只是依赖 HTTP 客户端。

在你提交任何东西之前，用提示词、模型 ID、素材 ID 和用户标识等输入构建一个确定性的请求哈希。然后把那个哈希连同 submitting 状态一起保存到你自己的数据库。

如果同一个哈希再次出现，返回已有的任务 而不是创建新的。

一旦你存下了提供商的任务 ID，就不要再次提交请求。只需用那个任务 ID 继续轮询。 :::