Theme

Upload file ​

Call /v1/file/upload to generate a presigned upload URL, then pass the returned download_url to APIs that accept public asset URLs.

http
PUT /v1/file/upload

This API does not accept file content directly. It issues an object-storage PUT URL; the client uploads the file to that URL. It is suited to pre-uploading images, video, and other media, and uses API Key authentication.

The default expiration for the presigned URL is 900 seconds; the minimum is 60 seconds and the maximum is 3600 seconds.

Headers ​

NameTypeRequiredDescription
stringYesRequest authentication. Use a Bearer Token, for example:
stringYesRequest content type; must be

Request body ​

NameTypeRequiredDescription
objectNoCustom headers for the upload request
stringNoFile MIME type, e.g. , ,
objectNoAdditional query parameters for the upload URL; pass an empty object if not needed

Request example ​

bash
curl -X PUT https://octopusx.ai/v1/file/upload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "Content-Type": "image/png"
    },
    "params": {}
  }'
bash
curl -X PUT https://octopusx.ai/v1/file/upload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "Content-Type": "video/mp4"
    },
    "params": {}
  }'

Response example ​

json
{
  "download_url": "https://xxxx.cn/uploads/file/2026/djlh2xxxxffqhkt.png",
  "expire": 3600,
  "method": "PUT",
  "upload_url": "https://.../uploads/user/12/20260519-abcdef.png?signature=..."
}

Response fields ​

NameTypeDescription
stringPublic URL you can pass directly to image, video, and task APIs after a successful upload
integerExpiration of the presigned URL, in seconds
stringUpload method; currently fixed to
stringSigned object-storage upload URL

Upload the file to the presigned URL ​

After you receive upload_url, send a PUT request with the file body to that URL. Content-Type must match the value you provided when requesting the presigned URL.

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

Use cases ​

Upload then use with asset-URL APIs ​

  1. Call /v1/file/upload to obtain upload_url and download_url
  2. PUT the file to upload_url
  3. Pass download_url as an input field to APIs that accept public asset URLs

Notes ​

WARNING

This API only issues an upload URL; it does not upload the file for you. The client must send a separate PUT to upload_url with the file content.