> ## 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.0 视频生成

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

# manxue-2.0

`manxue-2.0` 使用 JSON 请求体提交异步视频任务，支持文生视频、首帧生视频、首尾帧、多参考图和参考音频生成。

* 接口路径是 `POST /v1/videos`。
* 请求格式是 `application/json`。
* `seconds` 支持 `4` 到 `15` 秒。
* `resolution` 支持 `480P` 和 `720P`。
* 文生视频只需要 `model`、`prompt`、`seconds`、`ratio`、`resolution`。
* 参考图使用 `content` 数组中的 `image_url` 项，图片地址需要是公网 URL。
* 参考音频使用 `content` 数组中的 `audio_url` 项，并通过 `role: "reference_audio"` 标记。

## 方法与路径

```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.0",
      "prompt": "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
      "seconds": "8",
      "ratio": "16:9",
      "resolution": "720P",
      "generate_audio": false
    }'
  ```

  ```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.0",
      "prompt": "@image1；让画面中的人物自然转身，看向镜头并微笑",
      "seconds": "6",
      "ratio": "9:16",
      "resolution": "720P",
      "generate_audio": false,
      "content": [
        {
          "type": "text",
          "text": "@image1；让画面中的人物自然转身，看向镜头并微笑"
        },
        {
          "type": "image_url",
          "role": "first_frame",
          "image_url": {
            "url": "https://example.com/assets/first-frame.png"
          }
        }
      ]
    }'
  ```

  ```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.0",
      "prompt": "@image1；@image2；从首帧自然过渡到尾帧，保持人物服装和场景一致",
      "seconds": "10",
      "ratio": "16:9",
      "resolution": "720P",
      "generate_audio": false,
      "content": [
        {
          "type": "text",
          "text": "@image1；@image2；从首帧自然过渡到尾帧，保持人物服装和场景一致"
        },
        {
          "type": "image_url",
          "role": "first_frame",
          "image_url": {
            "url": "https://example.com/assets/opening-frame.png"
          }
        },
        {
          "type": "image_url",
          "role": "last_frame",
          "image_url": {
            "url": "https://example.com/assets/ending-frame.png"
          }
        }
      ]
    }'
  ```

  ```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.0",
      "prompt": "@image1；@image2；参考角色外观和场景氛围，生成一段慢镜头短片",
      "seconds": "12",
      "ratio": "16:9",
      "resolution": "480P",
      "generate_audio": false,
      "content": [
        {
          "type": "text",
          "text": "@image1；@image2；参考角色外观和场景氛围，生成一段慢镜头短片"
        },
        {
          "type": "image_url",
          "role": "reference_image",
          "image_url": {
            "url": "https://example.com/assets/character.png"
          }
        },
        {
          "type": "image_url",
          "role": "reference_image",
          "image_url": {
            "url": "https://example.com/assets/scene.png"
          }
        }
      ]
    }'
  ```

  ```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.0",
      "prompt": "@image1；根据音频内容自动拆分场景，生成连贯的视频镜头，镜头节奏跟随语气和情绪变化。",
      "seconds": "15",
      "ratio": "16:9",
      "resolution": "720P",
      "generate_audio": true,
      "content": [
        {
          "type": "text",
          "text": "@image1；请根据音频内容生成分镜、场景、动作和镜头变化，整体偏自然真实。"
        },
        {
          "type": "image_url",
          "role": "reference_image",
          "image_url": {
            "url": "https://example.com/assets/reference-image.png"
          }
        },
        {
          "type": "audio_url",
          "role": "reference_audio",
          "audio_url": {
            "url": "https://example.com/assets/reference-audio.mp3"
          }
        }
      ]
    }'
  ```

  ```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.0",
          "prompt": "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
          "seconds": "8",
          "ratio": "16:9",
          "resolution": "720P",
          "generate_audio": False,
      },
      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.0",
      prompt: "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
      seconds: "8",
      ratio: "16:9",
      resolution: "720P",
      generate_audio: false,
    }),
  });

  console.log(await response.json());
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]any{
  		"model":          "manxue-2.0",
  		"prompt":         "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
  		"seconds":        "8",
  		"ratio":          "16:9",
  		"resolution":     "720P",
  		"generate_audio": false,
  	}
  	body, _ := json.Marshal(payload)

  	req, _ := http.NewRequest("POST", "https://www.geeknow.top/v1/videos", bytes.NewReader(body))
  	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  	req.Header.Set("Content-Type", "application/json")

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Main {
      public static void main(String[] args) throws Exception {
          String json = """
          {
            "model": "manxue-2.0",
            "prompt": "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
            "seconds": "8",
            "ratio": "16:9",
            "resolution": "720P",
            "generate_audio": false
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://www.geeknow.top/v1/videos"))
              .header("Authorization", "Bearer YOUR_API_KEY")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(json))
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php
  $payload = [
      'model' => 'manxue-2.0',
      'prompt' => '清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感',
      'seconds' => '8',
      'ratio' => '16:9',
      'resolution' => '720P',
      'generate_audio' => false,
  ];

  $ch = curl_init('https://www.geeknow.top/v1/videos');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer YOUR_API_KEY',
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
      CURLOPT_RETURNTRANSFER => true,
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```
</RequestExample>

## 响应示例

<ResponseExample>
  ```json 200 - 提交成功 theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "manxue-2.0",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "video_url": ""
  }
  ```

  ```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.0`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频生成提示词。使用参考图时，建议在提示词中加入 `@image1`、`@image2` 等引用标记。
</ParamField>

<ParamField body="seconds" type="string">
  视频时长。支持 `4` 到 `15` 秒，建议按字符串传入，例如 `"8"`。
</ParamField>

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

<ParamField body="resolution" type="string">
  输出清晰度。支持 `480P`、`720P`，也兼容 `480p`、`720p` 写法。
</ParamField>

<ParamField body="generate_audio" type="boolean">
  是否生成音频或启用参考音频。使用 `content[].audio_url` 作为参考音频时，建议传 `true`。
</ParamField>

<ParamField body="content" type="array<object>">
  图生视频、参考图视频或参考音频视频使用的内容数组。第一项通常为文本，图片项使用 `type: "image_url"`，音频项使用 `type: "audio_url"`。
</ParamField>

<ParamField body="content[].type" type="string">
  内容类型。文本项为 `text`，图片项为 `image_url`，音频项为 `audio_url`。
</ParamField>

<ParamField body="content[].text" type="string">
  文本项内容。通常与顶层 `prompt` 保持一致。
</ParamField>

<ParamField body="content[].role" type="string">
  素材角色。图片常用值为 `first_frame`、`last_frame`、`reference_image`；参考音频使用 `reference_audio`。
</ParamField>

<ParamField body="content[].image_url.url" type="string">
  公网图片 URL。`manxue-2.0` 不接收 Base64 data URI。
</ParamField>

<ParamField body="content[].audio_url.url" type="string">
  公网音频 URL。使用参考音频时，`content[].type` 传 `audio_url`，`content[].role` 传 `reference_audio`。
</ParamField>

## Response

<ResponseField name="id" type="string">
  视频任务 ID。后续可用于 `GET /v1/videos/{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.0`。
</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/{id}/content` 下载结果。
</ResponseField>

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

## 使用场景

### 480P 文生视频

```json theme={null}
{
  "model": "manxue-2.0",
  "prompt": "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾，电影感",
  "seconds": "6",
  "ratio": "16:9",
  "resolution": "480P",
  "generate_audio": false
}
```

### 首帧生视频

```json theme={null}
{
  "model": "manxue-2.0",
  "prompt": "@image1；让画面中的人物自然转身，看向镜头并微笑",
  "seconds": "8",
  "ratio": "9:16",
  "resolution": "720P",
  "content": [
    {
      "type": "text",
      "text": "@image1；让画面中的人物自然转身，看向镜头并微笑"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/assets/first-frame.png"
      }
    }
  ]
}
```

### 多参考图视频

```json theme={null}
{
  "model": "manxue-2.0",
  "prompt": "@image1；@image2；参考角色外观和场景氛围，生成一段慢镜头短片",
  "seconds": "12",
  "ratio": "16:9",
  "resolution": "720P",
  "content": [
    {
      "type": "text",
      "text": "@image1；@image2；参考角色外观和场景氛围，生成一段慢镜头短片"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/assets/character.png"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/assets/scene.png"
      }
    }
  ]
}
```

### 参考图 + 参考音频视频

参考音频放在 `content` 数组中，使用 `type: "audio_url"` 和 `role: "reference_audio"`。提示词可以说明“根据音频内容拆分场景、节奏跟随语气和情绪变化”等要求。

```json theme={null}
{
  "model": "manxue-2.0",
  "prompt": "@image1；根据音频内容自动拆分场景，生成连贯的视频镜头，镜头节奏跟随语气和情绪变化。",
  "seconds": "15",
  "ratio": "16:9",
  "resolution": "720P",
  "generate_audio": true,
  "content": [
    {
      "type": "text",
      "text": "@image1；请根据音频内容生成分镜、场景、动作和镜头变化，整体偏自然真实。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/assets/reference-image.png"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://example.com/assets/reference-audio.mp3"
      }
    }
  ]
}
```

## 注意事项

* 请求格式为 `application/json`。
* `seconds` 支持 `4` 到 `15` 秒。
* `resolution` 支持 `480P` 和 `720P`。
* 图片字段接收公网 URL；Base64 data URI 不属于该字段的推荐输入格式。
* 音频参考通过 `content[].audio_url.url` 传入公网音频 URL，并使用 `role: "reference_audio"` 标记。
* 该模型归属特惠渠道系列，模型名固定使用 `manxue-2.0`。

## 相关接口

* [特惠渠道系列概览](./overview)
* [manxue-2.0 任务查询](./query)