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

# manxue-2.5 参考生视频

> 使用 JSON 请求调用 manxue-2.5 提交参考生视频任务。

# manxue-2.5 参考生视频

`manxue-2.5` 目前只支持参考生视频。请求必须在 `images` 中提供至少一张参考图，不能只传文字提示词。服务会返回异步任务 ID，后续通过查询接口获取视频结果。

## 模型规格

| 项目      | 说明                                                |
| ------- | ------------------------------------------------- |
| `model` | 固定传 `manxue-2.5`                                  |
| 请求格式    | `application/json`                                |
| 时长      | `seconds` 仅支持 `30` 秒                              |
| 画幅      | `ratio` 支持 `1:1`、`3:4`、`4:3`、`9:16`、`16:9`、`21:9` |
| 参考图     | `images` 必填，支持 `1` 到 `30` 张                       |

## 方法与路径

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

## 请求示例

<RequestExample>
  ```bash 参考生视频 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "manxue-2.5",
      "prompt": "参考图片中的人物外观和服装，人物自然走向镜头并回头微笑，镜头缓慢前推，保持真实光影和竖屏构图",
      "seconds": "30",
      "ratio": "9:16",
      "images": [
        "https://example.com/assets/person.png",
        "https://example.com/assets/street.png"
      ]
    }'
  ```

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

  resp = requests.post(
      "https://www.geeknow.top/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "manxue-2.5",
          "prompt": "参考产品图保持产品外观一致，生成一段镜头环绕产品的广告视频",
          "seconds": "30",
          "ratio": "16:9",
          "images": [
              "https://example.com/assets/product-front.png",
              "https://example.com/assets/product-side.png",
          ],
      },
      timeout=120,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://www.geeknow.top/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "manxue-2.5",
      prompt: "参考图片中的角色外观，生成一段自然行走的电影感视频",
      seconds: "30",
      ratio: "16:9",
      images: ["https://example.com/assets/character.png"],
    }),
  });

  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": "30",
    "url": null,
    "video_url": null,
    "metadata": {},
    "error": null
  }
  ```

  ```json 400 - 缺少参考图 theme={null}
  {
    "error": {
      "message": "images is required for reference video generation",
      "type": "invalid_request_error",
      "param": "images",
      "code": "invalid_request_error"
    }
  }
  ```

  ```json 400 - 参数错误 theme={null}
  {
    "error": {
      "message": "seconds must be 30",
      "type": "invalid_request_error",
      "param": "seconds",
      "code": "invalid_request_error"
    }
  }
  ```

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

## 认证

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

## Body

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

<ParamField body="prompt" type="string" required>
  视频生成提示词。描述参考图中的主体、动作、镜头和风格；不要把它当作文生视频请求使用。
</ParamField>

<ParamField body="seconds" type="string" required>
  输出视频时长，单位为秒。仅支持 `30`，建议按字符串传入：`"30"`。
</ParamField>

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

<ParamField body="images" type="array<string>" required>
  参考图片数组。至少传入 1 张，最多 30 张；每一项可以是公网图片 URL 或纯 Base64 字符串。不要传 data URI。
</ParamField>

## 参考图使用规则

* `images` 是参考生视频的必填字段，不能省略或传空数组。
* 多张图片用于共同约束人物、产品、场景或风格，不表示首帧和尾帧。
* 接口不接受 `first_image`、`last_image`、`referenceVideos` 或 `referenceAudios` 字段。
* 使用本地图片时，客户端需要先转换为纯 Base64 字符串；公网 URL 可直接放入数组。

## 注意事项

* 请求格式必须是 `application/json`。
* `seconds` 只能使用 `30`，不要传其它时长。
* `images` 数量不能超过 `30` 张，且图片需要可被服务端读取。
* 提交成功后读取响应中的 `id` 或 `task_id`，不要重复提交同一个任务。

## 相关接口

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