> ## 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.

# Upload File

> Call `/v1/file/upload` to generate a pre-signed upload URL, then pass the returned `download_url` to interfaces that accept public asset URLs.

# Upload File

This API does not directly accept file contents. Instead, it first issues an object storage `PUT` URL. After the client obtains the URL, it uploads the file on its own.

* Suitable for pre-uploading images, videos, and other media assets.
* Uses API Key authentication.
* The default expiration time is `900` seconds, with a minimum of `60` seconds and a maximum of `3600` seconds.

## Method and Path

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

## Request Example

### Upload Image

<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>

### Upload Video

<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 File to the Presigned URL

Once you have the `upload_url`, send a `PUT` request to that URL with the file contents. The `Content-Type` must match the value specified when requesting the presigned URL.

```bash theme={null}
# Upload a video (Content-Type must match the video/mp4 declared when requesting upload_url)
curl -X PUT "https://.../uploads/user/12/20260519-abcdef.mp4?signature=..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/video.mp4
```

## Response Example

<ResponseExample>
  ```json 200 - Pre-signed URL created 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 not configured 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>

## Authentication

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

## Body

<ParamField body="headers" type="object">
  Custom headers for the upload request.

  <ParamField body="Content-Type" type="string">
    The file MIME type, such as `image/png`, `image/jpeg`, or `video/mp4`.
  </ParamField>
</ParamField>

<ParamField body="params" type="object">
  Additional query parameters for the upload URL. Can be an empty object `{}` if no extra parameters are needed.
</ParamField>

## Response

<ResponseField name="download_url" type="string">
  The public URL that can be directly passed to image, video, and task endpoints after a successful upload.
</ResponseField>

<ResponseField name="expire" type="integer">
  The expiration time of the pre-signed URL in seconds.
</ResponseField>

<ResponseField name="method" type="string">
  The upload method, currently fixed as `PUT`.
</ResponseField>

<ResponseField name="upload_url" type="string">
  The signed object storage upload URL.
</ResponseField>

## Use Cases

### Use it as a media URL after uploading

1. Call `/v1/file/upload` to obtain `upload_url` and `download_url`.
2. Upload the file by sending a `PUT` request to `upload_url`.
3. Pass `download_url` as the input field to interfaces that accept public media URLs.

## Notes

<Warning>
  This endpoint only issues the upload URL; it does not upload the file for you. Actual file upload requires the client to send another `PUT` request to `upload_url`.
</Warning>

## Related APIs

* [Video Series Overview](../videos/overview)
* [Image Series Overview](../images/overview)