Wan3 创建任务#

本接口用于创建 Wan3 视频生成任务。任务采用异步处理方式，创建成功后需使用返回的任务 ID 查询生成状态和结果。

准备工作#

请前往 UniGateway API Keys 创建或获取 API Key。

确认 API Key 已启用且具有目标模型的访问权限，工作区余额和消费限额满足调用要求。模型能力、价格和可用性以 UniGateway 模型库、控制台或当前账户的接口实时返回为准。

将 API Key 保存到服务端环境变量 UNIGATEWAY_API_KEY 或受控的密钥管理服务中，不要写入公开代码、浏览器端代码或日志。

接口与鉴权#

完整请求地址为 https://api.unigateway.ai/v1/videos。

请求结构#

若同时提供两处提示词，以 metadata.input.prompt 为准。素材应放在 metadata.input.media 中，生成参数应放在 metadata.parameters 中。

生成参数#

以下字段均位于 metadata.parameters 中，均为可选参数。

构造请求时应保留 false、0、-1 等显式值，不要将它们作为空值删除。不同参数的范围不同，例如 seed=0 合法，但 duration=0 不合法。

顶层 duration、seconds 为兼容字段。建议仅使用 metadata.parameters.duration 设置时长；重复提供时，该字段优先。

素材类型与限制#

无需先创建素材库，直接在 metadata.input.media 中提供素材。

每项素材的字段如下：

组合限制：

• 首帧和尾帧可以组合，但不能与参考图像、参考视频、参考音频、file 或 link 混用。
• file 与 link 不能同时使用。
• 使用 file 或 link 时，必须启用 prompt_extend。

推荐使用服务端可直接访问的 HTTPS 素材 URL。图像类输入还接受 data:image/...;base64,...。不要填写本机文件路径；签名 URL 应保留完整查询参数，并在任务处理期间保持有效。

数量和组合校验通过不代表素材一定可用。素材格式、编码、实际时长和内容还需通过服务端校验。

示例一：文本生成视频#

以下示例使用 Prime 模型，请求生成 720P、16:9、5 秒且不带音频的视频。

{
  "model": "wan3.0-video-prime",
  "prompt": "A golden retriever running along a quiet beach at sunrise, cinematic, smooth camera movement",
  "metadata": {
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": false,
      "prompt_extend": true,
      "watermark": false,
      "seed": -1
    }
  }
}

调用普通版时，将 model 改为 wan3.0-video，并确认 API Key 具有相应访问权限。实际时长和用量以查询响应为准。

示例二：参考视频生成#

将示例 URL 替换为实际可访问的视频地址。

{
  "model": "wan3.0-video-prime",
  "prompt": "Apply a cinematic color grade and smooth camera movement",
  "metadata": {
    "input": {
      "media": [
        {
          "type": "reference_video",
          "url": "https://example.com/reference.mp4"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": false,
      "prompt_extend": true,
      "watermark": false,
      "seed": -1
    }
  }
}

计费时长包含实际输入视频时长与实际输出视频时长。不要仅按请求中的输出时长估算最终用量。

创建响应#

以下为关键字段示例，任务 ID 为占位值，实际响应可能包含其他字段：

{
  "id": "PUBLIC_TASK_ID",
  "object": "video",
  "model": "wan3.0-video-prime",
  "status": "queued",
  "progress": 0
}

保存 id，使用相同 API Key 调用 GET https://api.unigateway.ai/v1/videos/{task_id}。建议每隔约 15 秒查询一次。当 status=completed 且 metadata.url 非空时，获取视频结果。

错误处理#

提交 duration=31 等非法参数时，可返回 HTTP 400：

{
  "code": "invalid_wan3_request",
  "message": "duration must be -1 or an integer from 2 to 30",
  "data": null
}

根据错误信息修正参数后再提交。遇到鉴权、权限或额度错误时，检查 API Key 状态、模型访问权限、工作区余额及消费限额。

若请求已被受理，后续执行仍可能失败，应通过查询接口确认最终状态。创建请求超时或发生通信异常时，不要自动重复提交；先核查是否已创建任务，避免产生重复任务和额外费用。