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

# 上传视频

> 上传视频获取 URL，用于视频生成和参考视频输入

<Note>
  **文档 Playground 不支持文件上传**：请使用下方的 cURL、Python 或 JavaScript 代码示例进行测试。
</Note>

## 为什么需要先上传视频？

1. **统一输入方式** - 本地视频先上传成公网 URL，便于后续接口复用
2. **减少重复传输** - 上传一次后可以在多个视频任务中重复使用

## Authorizations

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 进行认证

  获取 API Key：访问 [API Key 管理页面](https://toapis.com/console/token)

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="file" type="file" required>
  视频文件

  **支持的格式：**

  * MP4 (.mp4)
  * WebM (.webm)
  * MOV (.mov)

  **限制：**

  * 最大文件大小：50MB
</ParamField>

<ParamField body="purpose" type="string">
  上传目的（可选）

  默认值：`generation`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  请求是否成功
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="返回数据">
    <ResponseField name="id" type="string">
      上传记录 ID，用于追踪
    </ResponseField>

    <ResponseField name="url" type="string">
      视频的公开访问 URL，可直接用于视频生成接口
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      视频的 MIME 类型，如 `video/mp4`
    </ResponseField>

    <ResponseField name="size" type="integer">
      视频文件大小（字节）
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/uploads/videos \
    --header 'Authorization: Bearer <token>' \
    --form 'file=@/path/to/your/video.mp4'
  ```

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

  with open('video.mp4', 'rb') as f:
      response = requests.post(
          "https://toapis.com/v1/uploads/videos",
          headers={
              "Authorization": "Bearer your-ToAPIs-key"
          },
          files={
              "file": f
          }
      )

  result = response.json()
  video_url = result['data']['url']
  print(f"视频 URL: {video_url}")
  ```

  ```javascript JavaScript theme={null}
  (async () => {
  const fileInput = document.createElement('input');
  fileInput.type = 'file';
  fileInput.accept = 'video/mp4,video/webm,video/quicktime';
  fileInput.click();
  await new Promise(resolve => fileInput.onchange = resolve);

  const formData = new FormData();
  formData.append('file', fileInput.files[0]);

  const uploadResponse = await fetch('https://toapis.com/v1/uploads/videos', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-ToAPIs-key'
    },
    body: formData
  });

  const uploadResult = await uploadResponse.json();
  console.log('上传结果:', uploadResult);
  })();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 成功 theme={null}
  {
    "success": true,
    "message": "",
    "data": {
      "id": "upload_abc12345",
      "url": "https://files.toapis.com/uploads/123/videos/1737568800_abc12345.mp4",
      "mime_type": "video/mp4",
      "size": 1892345
    }
  }
  ```

  ```json 400 错误请求 theme={null}
  {
    "success": false,
    "message": "Unsupported or invalid video file. Allowed: MP4, WebM, MOV"
  }
  ```

  ```json 400 文件过大 theme={null}
  {
    "success": false,
    "message": "Video too large. Maximum size is 50MB"
  }
  ```
</ResponseExample>