视频生成 API

1XM 视频生成 API 使用异步任务模式。POST /v1/videos 只负责创建任务并返回任务 ID，不会等待视频生成完成；客户端需要用 GET /v1/videos/{task_id} 轮询状态，任务完成后读取结果 URL 或通过内容代理接口下载视频。

接入信息

项目	值
Base URL	`https://api.1xm.ai/v1`
创建任务	`POST /videos`
查询任务	`GET /videos/{task_id}`
下载内容	`GET /videos/{task_id}/content`
示例模型	`seedance2-fast`
认证方式	`Authorization: Bearer sk-你的Key`

注意

/v1/videos 不是同步接口。创建成功只表示任务已提交，视频结果需要通过查询接口获取。

调用流程

客户服务端调用 POST /v1/videos 创建视频任务。
保存响应里的 id，每 5-10 秒 调用 GET /v1/videos/{id} 查询状态。
当 status 变为 completed 时，从 metadata.url 读取视频 URL。
如果你希望由 1XM 代理下载视频，可以调用 GET /v1/videos/{id}/content。

文本生成视频

bash

curl -X POST "https://api.1xm.ai/v1/videos" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-fast",
    "prompt": "一只龙虾在海边跳舞，夕阳，电影感，16:9",
    "duration": 5,
    "size": "1280x720",
    "options": {
      "generate_audio": true,
      "quality": "720p"
    }
  }'

成功创建后返回 200 OK：

json

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "seedance2-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1789990000
}

字段说明：

字段	说明
`id`	视频任务 ID，后续查询和下载都使用这个值
`task_id`	兼容字段，值通常与 `id` 相同
`status`	创建后通常为 `queued`
`progress`	任务进度，范围 `0-100`
`created_at`	Unix 秒级时间戳

图片生成视频

单张首帧图：

bash

curl -X POST "https://api.1xm.ai/v1/videos" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-fast",
    "prompt": "让图片里的主体自然转身，镜头轻微推进",
    "image": "https://example.com/first-frame.jpg",
    "duration": 5,
    "size": "1280x720"
  }'

多张参考图：

bash

curl -X POST "https://api.1xm.ai/v1/videos" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-fast",
    "prompt": "参考图片风格生成一段产品展示视频",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 5,
    "size": "1280x720"
  }'

图片输入建议使用可公开访问的 HTTPS URL。部分模型也支持 data:image/...;base64,...，具体以模型能力为准。

查询任务

bash

curl "https://api.1xm.ai/v1/videos/task_xxx" \
  -H "Authorization: Bearer sk-你的Key"

处理中：

json

{
  "id": "task_xxx",
  "object": "video",
  "model": "seedance2-fast",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1789990000
}

成功：

json

{
  "id": "task_xxx",
  "object": "video",
  "model": "seedance2-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1789990000,
  "completed_at": 1789990060,
  "metadata": {
    "url": "https://cdn.example.com/video.mp4"
  }
}

失败：

json

{
  "id": "task_xxx",
  "object": "video",
  "model": "seedance2-fast",
  "status": "failed",
  "progress": 100,
  "error": {
    "message": "content policy rejected",
    "code": "failed"
  }
}

任务状态：

状态	含义
`queued`	任务已创建，等待处理
`in_progress`	视频正在生成
`completed`	视频已生成，结果 URL 在 `metadata.url`
`failed`	任务失败，错误信息在 `error.message`

下载视频内容

任务完成后，推荐优先使用 metadata.url。如果结果 URL 有跨域、签名或下载限制，可以使用 1XM 内容代理接口：

bash

curl -L "https://api.1xm.ai/v1/videos/task_xxx/content" \
  -H "Authorization: Bearer sk-你的Key" \
  -o output.mp4

如果任务还没有完成，内容接口会返回错误。请先查询任务状态，确认 status 为 completed 后再下载。

参数说明

参数	类型	必填	说明
`model`	string	是	视频模型名称，例如 `seedance2-fast`
`prompt`	string	条件必填	文本提示词。没有图片或视频参考输入时必填
`image`	string	否	单张首帧图 URL
`images`	string[]	否	多张参考图 URL
`duration`	number	否	成片时长，单位秒
`size`	string	否	尺寸或画幅，例如 `1280x720`、`720x1280`、`16:9`
`options`	object	否	模型高级参数

常用 options：

参数	说明
`duration` / `duration_sec`	成片时长，单位秒
`aspect_ratio` / `ratio`	画幅，例如 `16:9`、`9:16`、`1:1`
`quality` / `resolution`	质量或分辨率，取决于模型支持
`generate_audio`	是否生成音频，取决于模型支持
`language`	语音或字幕相关语言参数，取决于模型支持
`negative_prompt`	负向提示词
`seed`	随机种子
`first_frame_url`	首帧图 URL；显式传入时优先于顶层 `image`
`last_frame_url`	尾帧图 URL
`image_urls`	参考图 URL 列表
`reference_image_urls`	参考图 URL 列表
`reference_video_urls`	参考视频 URL 列表
`imitation_video_urls`	参考视频 URL 列表

顶层参数和 options 同时存在时，options 中显式传入的值优先。例如同时传 size: "1280x720" 和 options.aspect_ratio: "9:16"，会优先使用 options.aspect_ratio。

Node.js 示例

javascript

const apiKey = process.env.ONE_XM_API_KEY;

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function createVideoTask() {
  const res = await fetch('https://api.1xm.ai/v1/videos', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedance2-fast',
      prompt: '一只龙虾在海边跳舞，夕阳，电影感，16:9',
      duration: 5,
      size: '1280x720'
    })
  });

  if (!res.ok) {
    throw new Error(await res.text());
  }

  return res.json();
}

async function pollVideoTask(taskId) {
  while (true) {
    const res = await fetch(`https://api.1xm.ai/v1/videos/${taskId}`, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });

    if (!res.ok) {
      throw new Error(await res.text());
    }

    const task = await res.json();

    if (task.status === 'completed') {
      return task.metadata?.url;
    }

    if (task.status === 'failed') {
      throw new Error(task.error?.message || 'video task failed');
    }

    await sleep(5000);
  }
}

const task = await createVideoTask();
const videoUrl = await pollVideoTask(task.id);
console.log(videoUrl);

Python 示例

python

import os
import time
import requests

api_key = os.environ["ONE_XM_API_KEY"]
base_url = "https://api.1xm.ai/v1"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

create_resp = requests.post(
    f"{base_url}/videos",
    headers=headers,
    json={
        "model": "seedance2-fast",
        "prompt": "一只龙虾在海边跳舞，夕阳，电影感，16:9",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=30,
)
create_resp.raise_for_status()
task = create_resp.json()

while True:
    query_resp = requests.get(
        f"{base_url}/videos/{task['id']}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=30,
    )
    query_resp.raise_for_status()
    current = query_resp.json()

    if current["status"] == "completed":
        print(current.get("metadata", {}).get("url"))
        break

    if current["status"] == "failed":
        raise RuntimeError(current.get("error", {}).get("message", "video task failed"))

    time.sleep(5)

接入建议

保存任务 id，并把它与你自己的订单、素材或用户请求绑定。
不要对查询接口做高频轮询，建议 5-10 秒 一次；连续失败时使用退避重试。
不要在前端直接暴露 API Key；由你的服务端调用 1XM API。
图片和视频参考 URL 尽量使用稳定、可公开访问的 HTTPS 地址。
对用户侧产品，建议展示 queued、in_progress、completed、failed 四种状态。

常见问题

创建任务后会立即返回视频吗？

不会。视频生成耗时较长，创建接口只返回任务 ID。请用查询接口轮询到 completed 后再读取结果。

`metadata.url` 为空怎么办？

先确认任务状态是 completed。如果仍为空，可以稍后重试查询，或使用 /v1/videos/{task_id}/content 内容代理接口。

能否直接在浏览器里调用？

不建议。浏览器里暴露 API Key 会带来安全风险。推荐由你的后端创建和查询任务，再把状态或结果返回给前端。

视频生成 API ​

接入信息 ​

调用流程 ​

文本生成视频 ​

图片生成视频 ​

查询任务 ​

下载视频内容 ​

参数说明 ​

Node.js 示例 ​

Python 示例 ​

接入建议 ​

常见问题 ​

创建任务后会立即返回视频吗？ ​

metadata.url 为空怎么办？ ​

能否直接在浏览器里调用？ ​

视频生成 API

接入信息

调用流程

文本生成视频

图片生成视频

查询任务

下载视频内容

参数说明

Node.js 示例

Python 示例

接入建议

常见问题

创建任务后会立即返回视频吗？

`metadata.url` 为空怎么办？

能否直接在浏览器里调用？