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

# 上传文件

> 调用 `/v1/file/upload` 生成预签名上传地址，再把返回的 `download_url` 传给接受公网素材 URL 的接口。

# 上传文件

这个接口不直接接收文件内容，而是先签发一个对象存储 `PUT` 地址。客户端拿到地址后再自行上传文件。

* 适合图片、视频和其他媒体素材的预上传。
* 使用 API Key 认证。
* 默认过期时间为 `900` 秒，最短 `60` 秒，最长 `3600` 秒。

## 方法与路径

```http theme={null}
PUT /v1/file/upload
```

## 请求示例

### 上传图片

<CodeGroup>
  ```bash theme={null}
  curl -X PUT https://octopusx.ai/v1/file/upload \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "headers": {
        "Content-Type": "image/png"
      },
      "params": {}
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.put(
      "https://octopusx.ai/v1/file/upload",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "headers": {
              "Content-Type": "image/png"
          },
          "params": {}
      },
      timeout=30,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/file/upload", {
    method: "PUT",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      headers: {
        "Content-Type": "image/png"
      },
      params: {}
    }),
  });

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

### 上传视频

<CodeGroup>
  ```bash theme={null}
  curl -X PUT https://octopusx.ai/v1/file/upload \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "headers": {
        "Content-Type": "video/mp4"
      },
      "params": {}
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.put(
      "https://octopusx.ai/v1/file/upload",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "headers": {
              "Content-Type": "video/mp4"
          },
          "params": {}
      },
      timeout=30,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/file/upload", {
    method: "PUT",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      headers: {
        "Content-Type": "video/mp4"
      },
      params: {}
    }),
  });

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

### 上传文件到预签名地址

拿到 `upload_url` 后，对目标地址发起 `PUT` 请求上传文件本体。`Content-Type` 须与请求预签名地址时传入的值一致。

```bash theme={null}
# 上传视频（Content-Type 须与获取 upload_url 时声明的 video/mp4 一致）
curl -X PUT "https://.../uploads/user/12/20260519-abcdef.mp4?signature=..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/video.mp4
```

## 响应示例

<ResponseExample>
  ```json 200 - 预签名地址已创建 theme={null}
  {
    "download_url": "https://xxxx.cn/uploads/file/2026/djlh2xxxxffqhkt.png",
    "expire": 3600,
    "method": "PUT",
    "upload_url": "https://.../uploads/user/12/20260519-abcdef.png?signature=..."
  }
  ```

  ```json 200 - OSS 未配置 theme={null}
  {
    "error": {
      "code": "",
      "message": "oss storage is not configured",
      "type": "aix_api_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "",
      "message": "Invalid token (request id: 7ca08841-73ab-11f1-92b8-1a9776f84c80)",
      "type": "aix_api_error"
    }
  }
  ```
</ResponseExample>

## 认证

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

## Body

<ParamField body="headers" type="object">
  上传请求的自定义头部。

  <ParamField body="Content-Type" type="string">
    文件 MIME 类型，例如 `image/png`、`image/jpeg`、`video/mp4`。
  </ParamField>
</ParamField>

<ParamField body="params" type="object">
  上传 URL 的附加查询参数。如果不需要额外参数，可以传空对象 `{}`。
</ParamField>

## Response

<ResponseField name="download_url" type="string">
  上传成功后可直接传给图像、视频和任务接口的公网 URL。
</ResponseField>

<ResponseField name="expire" type="integer">
  预签名 URL 的过期时间，单位秒。
</ResponseField>

<ResponseField name="method" type="string">
  上传方法，当前固定为 `PUT`。
</ResponseField>

<ResponseField name="upload_url" type="string">
  带签名的对象存储上传地址。
</ResponseField>

## 使用场景

### 上传后再用于素材 URL 接口

1. 调用 `/v1/file/upload` 取得 `upload_url` 与 `download_url`。
2. 对 `upload_url` 发起 `PUT` 上传文件。
3. 在接受公网素材 URL 的接口中把 `download_url` 作为输入字段传入。

## 注意事项

<Warning>
  这个接口只负责签发上传地址，不会替你上传文件本身。真正的文件上传需要客户端对 `upload_url` 再发一次 `PUT` 请求。
</Warning>

## 相关接口

* [视频系列概览](../videos/overview)
* [图像系列概览](../images/overview)