> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.geeknow.top/llms.txt
> Use this file to discover all available pages before exploring further.

# manxue-2.5 视频生成

> 使用 `POST /v1/videos` 调用 `manxue-2.5` 提交 JSON 视频生成任务。

# manxue-2.5 视频生成

`manxue-2.5` 通过 `POST /v1/videos` 提交异步视频任务。请求体使用 `application/json`，核心字段为 `model`、`prompt`、`duration`、`ratio`、`resolution`，参考素材通过 `referenceImages`、`referenceVideos`、`referenceAudios` 传入。

## 模型规格

| 项目      | 说明                                    |
| ------- | ------------------------------------- |
| `model` | 固定传 `manxue-2.5`                      |
| 请求格式    | `application/json`                    |
| 时长      | `duration` 支持 `4` 到 `29` 秒            |
| 画幅      | `ratio` 支持 `16:9`、`9:16`、`1:1`、`21:9` |
| 清晰度     | `resolution` 支持 `480p`、`720p`         |
| 参考图     | `referenceImages` 最多 `30` 张           |
| 参考视频    | `referenceVideos` 最多 `10` 个           |
| 参考音频    | `referenceAudios` 最多 `10` 个           |

## 方法与路径

```http theme={null}
POST /v1/videos
```

## 请求示例

<RequestExample>
  ```bash 文生视频 cURL theme={null}
  curl -X POST https://td.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "manxue-2.5",
      "prompt": "清晨的海边公路，车辆沿海岸线行驶，低角度跟拍，真实光影，电影感",
      "duration": 8,
      "ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash 多参考图 cURL theme={null}
  curl -X POST https://td.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "manxue-2.5",
      "prompt": "参考图片中的人物外观、服装和场景氛围，生成一段自然行走的竖屏视频，镜头轻微前推",
      "duration": 12,
      "ratio": "9:16",
      "resolution": "720p",
      "referenceImages": [
        "https://example.com/assets/person.png",
        "https://example.com/assets/location.png"
      ]
    }'
  ```

  ```bash 参考图 + 参考视频 + 参考音频 cURL theme={null}
  curl -X POST https://td.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "manxue-2.5",
      "prompt": "参考产品图保持主体一致，参考视频的镜头运动和动作节奏，参考音频的情绪生成一条广告短片",
      "duration": 20,
      "ratio": "16:9",
      "resolution": "720p",
      "referenceImages": [
        "https://example.com/assets/product-front.png",
        "https://example.com/assets/product-side.png"
      ],
      "referenceVideos": [
        "https://example.com/assets/camera-motion.mp4"
      ],
      "referenceAudios": [
        "https://example.com/assets/music.mp3"
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://td.geeknow.top/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "manxue-2.5",
          "prompt": "清晨的海边公路，车辆沿海岸线行驶，低角度跟拍，真实光影，电影感",
          "duration": 8,
          "ratio": "16:9",
          "resolution": "720p",
      },
      timeout=120,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://td.geeknow.top/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "manxue-2.5",
      prompt: "清晨的海边公路，车辆沿海岸线行驶，低角度跟拍，真实光影，电影感",
      duration: 8,
      ratio: "16:9",
      resolution: "720p",
    }),
  });

  console.log(await response.json());
  ```
</RequestExample>

## 响应示例

<ResponseExample>
  ```json 200 - 提交成功 theme={null}
  {
    "id": "manxue-2.5_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "task_id": "manxue-2.5_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "object": "video",
    "model": "manxue-2.5",
    "status": "queued",
    "progress": 0,
    "created_at": 1782690295,
    "completed_at": null,
    "seconds": "8",
    "url": null,
    "video_url": null,
    "metadata": {},
    "error": null
  }
  ```

  ```json 400 - 参数错误 theme={null}
  {
    "error": {
      "message": "prompt is required",
      "type": "invalid_request_error",
      "param": "prompt",
      "code": "invalid_request_error"
    }
  }
  ```

  ```json 401 - 认证失败 theme={null}
  {
    "error": {
      "message": "invalid token",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 - 额度不足 theme={null}
  {
    "error": {
      "message": "insufficient quota",
      "type": "insufficient_quota",
      "code": "insufficient_quota"
    }
  }
  ```

  ```json 429 - 请求过多 theme={null}
  {
    "error": {
      "message": "rate limit exceeded",
      "type": "rate_limit_error",
      "code": "rate_limit_exceeded"
    }
  }
  ```
</ResponseExample>

## 认证

使用 Bearer Token 鉴权：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

JSON 请求还需要携带：

```http theme={null}
Content-Type: application/json
```

## Body

<ParamField body="model" type="string" required>
  模型名称。固定传 `manxue-2.5`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频生成提示词。建议明确主体、动作、镜头、风格、画面节奏，以及参考素材在任务中的作用。
</ParamField>

<ParamField body="duration" type="integer">
  输出视频时长，单位为秒。支持 `4` 到 `29` 的整数值。建议显式传入，避免依赖渠道默认值。
</ParamField>

<ParamField body="ratio" type="string">
  画幅比例。支持 `16:9`、`9:16`、`1:1`、`21:9`。
</ParamField>

<ParamField body="resolution" type="string">
  输出清晰度。支持 `480p`、`720p`。未明确选择时，通常按渠道默认清晰度处理。
</ParamField>

<ParamField body="referenceImages" type="array<string>">
  参考图片 URL 数组，最多 `30` 张。成员应为服务端可访问的公网 `http://` 或 `https://` 图片地址。
</ParamField>

<ParamField body="referenceVideos" type="array<string>">
  参考视频 URL 数组，最多 `10` 个。适合传入动作节奏、镜头运动、构图或画面风格参考。
</ParamField>

<ParamField body="referenceAudios" type="array<string>">
  参考音频 URL 数组，最多 `10` 个。适合传入旁白、音乐、节奏或情绪参考。
</ParamField>

## Response

<ResponseField name="id" type="string">
  视频任务 ID。后续可用于 `GET /v1/videos/{task_id}` 查询。
</ResponseField>

<ResponseField name="task_id" type="string">
  视频任务 ID 的兼容字段。通常与 `id` 相同。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，通常为 `video`。
</ResponseField>

<ResponseField name="model" type="string">
  本次任务使用的模型，例如 `manxue-2.5`。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态。常见值为 `queued`、`in_progress`、`completed`、`failed`。
</ResponseField>

<ResponseField name="progress" type="number">
  任务进度，常见范围为 `0` 到 `100`。部分上游不会稳定更新该字段，业务侧应以终态状态为准。
</ResponseField>

<ResponseField name="video_url" type="string">
  任务完成后的视频地址。也可以使用 `GET /v1/videos/{task_id}/content` 下载结果。
</ResponseField>

<ResponseField name="metadata" type="object">
  任务元信息。上游可能返回缓存状态、内容下载地址、过期时间或计费用量等字段。
</ResponseField>

<ResponseField name="error" type="object">
  任务失败或接口错误时返回的错误对象，通常包含 `message` 和 `code`。
</ResponseField>

## 请求构造规则

| 场景    | 字段组合                                                        |
| ----- | ----------------------------------------------------------- |
| 文生视频  | `model`、`prompt`、`duration`、`ratio`、`resolution`            |
| 多参考图  | 文生字段加 `referenceImages`，最多 `30` 张                           |
| 参考视频  | 文生字段加 `referenceVideos`，最多 `10` 个                           |
| 参考音频  | 文生字段加 `referenceAudios`，最多 `10` 个                           |
| 多模态参考 | 文生字段加 `referenceImages`、`referenceVideos`、`referenceAudios` |

## 注意事项

* 请求格式为 `application/json`。
* `duration` 使用整数秒，支持 `4` 到 `29` 秒。
* 参考素材字段传 URL 字符串数组，不要把本地文件路径直接写入请求体。
* `referenceImages`、`referenceVideos`、`referenceAudios` 可以组合使用，但应分别遵守数量上限。
* 如果需要特定素材角色约束，请在 `prompt` 中描述角色，并把图片放入 `referenceImages`。

## 相关接口

* [manxue-2.5 视频概览](./overview)
* [manxue-2.5 查询视频任务](./query)
* [视频模型支持矩阵](/api-reference/videos/model-matrix)