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

# 下载视频

> 下载已完成的视频文件数据

## 简介

下载视频接口用于获取已完成的视频文件数据。

<Warning>
  此接口仅 Sora 2 模型支持。其他模型（Veo、豆包 Seedance）在任务成功后，视频URL会直接包含在查询任务接口的响应中，无需额外下载步骤。
</Warning>

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 查询参数

<ParamField query="id" type="string" required>
  视频ID，由查询任务接口返回的 `task_id`
</ParamField>

## cURL 示例

```bash theme={null}
curl -X GET "https://api.mixroute.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## 响应示例

```json theme={null}
{
  "success": true,
  "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "format": "mp4",
  "size": 15728640,
  "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
  "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
}
```

## 响应字段说明

| 字段名 | 类型 | 说明 |
| - | - | - |
| `success` | boolean | 是否成功 |
| `generation_id` | string | 生成ID（与 videoId 相同） |
| `task_id` | string | 任务ID |
| `format` | string | 视频格式（固定为 `"mp4"`） |
| `size` | number | 视频文件大小（字节） |
| `base64` | string | Base64 编码的视频数据 |
| `data_url` | string | Data URL 格式的视频数据，可直接用于前端 `<video>` 标签 |

## 使用说明

### 前端使用 data\_url

`data_url` 字段可以直接用于 HTML `<video>` 标签：

```html theme={null}
<video src="data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..." controls></video>
```

### 下载保存文件

#### Node.js（服务端）

将 MixRoute Key 保留在服务端，浏览器应调用自己的后端，不要嵌入 Key。此接口返回包含 Base64 的 JSON，而不是 MP4 二进制流。

```javascript theme={null}
import { writeFile } from "node:fs/promises";

const apiKey = process.env.MIXROUTE_API_KEY;
if (!apiKey) throw new Error("MIXROUTE_API_KEY is required");
const url = new URL("https://api.mixroute.ai/v1/video/generations/download");
url.searchParams.set("id", "TASK_ID");
const response = await fetch(url, {
  headers: { Authorization: "Bearer " + apiKey },
  signal: AbortSignal.timeout(120000),
});
if (!response.ok) throw new Error("Download HTTP error: " + response.status);
const data = await response.json();
if (data.success !== true || typeof data.base64 !== "string" || !data.base64) {
  throw new Error(data.message || "No downloadable video in response");
}
await writeFile("video.mp4", Buffer.from(data.base64, "base64"));
```

#### Python 示例

```python theme={null}
import base64
import os
from pathlib import Path
import requests

def download_video(task_id, output_path="video.mp4"):
    response = requests.get(
        "https://api.mixroute.ai/v1/video/generations/download",
        params={"id": task_id},
        headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
        timeout=120,
    )
    response.raise_for_status()
    result = response.json()
    if result.get("success") is not True or not result.get("base64"):
        raise RuntimeError(result.get("message") or "No downloadable video in response")
    video = base64.b64decode(result["base64"], validate=True)
    Path(output_path).write_bytes(video)
    return output_path

if __name__ == "__main__":
    print(download_video("TASK_ID"))
```

## 完整流程示例（Sora 2）

### 1. 提交视频生成任务

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只可爱的小猫在花园里玩耍",
    "seconds": "4",
    "size": "720x1280"
  }'
```

响应：

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "submitted",
  "format": "mp4"
}
```

### 2. 查询任务状态（轮询直到成功）

```bash theme={null}
curl -X GET "https://api.mixroute.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

查询返回成功终止状态（`succeeded`、`SUCCESS` 或 `completed`）后，再进入下一步。

### 3. 下载视频文件

```bash theme={null}
curl -X GET "https://api.mixroute.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## 注意事项

* 下载接口返回的是 Base64 编码的视频数据，适合直接在前端展示或保存
* 对于大文件，建议使用流式下载或直接使用 URL 下载
* 视频格式固定为 MP4

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.mixroute.ai/v1/video/generations/download?id=video_xxx' \
    --header 'Authorization: Bearer sk-xxxxxxxxxx'
  ```

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

  url = "https://api.mixroute.ai/v1/video/generations/download"
  params = {"id": "video_xxx"}
  headers = {"Authorization": "Bearer sk-xxxxxxxxxx"}

  response = requests.get(url, params=params, headers=headers)
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from "node:fs/promises";

  const apiKey = process.env.MIXROUTE_API_KEY;
  if (!apiKey) throw new Error("MIXROUTE_API_KEY is required");
  const url = new URL("https://api.mixroute.ai/v1/video/generations/download");
  url.searchParams.set("id", "TASK_ID");
  const response = await fetch(url, {
    headers: { Authorization: "Bearer " + apiKey },
    signal: AbortSignal.timeout(120000),
  });
  if (!response.ok) throw new Error("Download HTTP error: " + response.status);
  const data = await response.json();
  if (data.success !== true || typeof data.base64 !== "string" || !data.base64) {
    throw new Error(data.message || "No downloadable video in response");
  }
  await writeFile("video.mp4", Buffer.from(data.base64, "base64"));
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->get('https://api.mixroute.ai/v1/video/generations/download', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx'
      ],
      'query' => ['id' => 'video_xxx']
  ]);
  echo $response->getBody();
  ```

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

  import (
      "net/http"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://api.mixroute.ai/v1/video/generations/download?id=video_xxx", nil)
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/video/generations/download?id=video_xxx"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .GET()
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/video/generations/download?id=video_xxx')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "generation_id": "video_xxx",
    "task_id": "video_xxx",
    "format": "mp4",
    "size": 15728640,
    "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE...",
    "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE..."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.