POST
https://octopusx.ai
/
api
/
upload
/
presign
Upload Image
curl --request POST \
  --url https://octopusx.ai/api/upload/presign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_name": "<string>",
  "content_type": "<string>",
  "expires_in": 123,
  "prefix": "<string>"
}
'
{
  "success": true,
  "message": "",
  "data": {
    "method": "PUT",
    "upload_url": "https://.../uploads/user/12/20260519-abcdef.png?signature=...",
    "object_key": "uploads/user/12/20260519-abcdef.png",
    "public_url": "https://.../uploads/user/12/20260519-abcdef.png",
    "expires_in": 900,
    "content_type": "image/png"
  }
}

​
Upload Image

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, the first frame of a video, and other media assets.
  • Uses API Key authentication, but the returned structure is wrapped in /api/* success/message/data.
  • The default expiration time is 900 seconds, with a minimum of 60 seconds and a maximum of 3600 seconds.
  • When prefix is not explicitly provided, the system automatically generates the uploads/user/{id} prefix based on the current user.

​
Method and Path

POST /api/upload/presign

​
Request Example

curl -X POST https://octopusx.ai/api/upload/presign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "input.png",
    "content_type": "image/png",
    "expires_in": 900
  }'

​
Response Example

{
  "success": true,
  "message": "",
  "data": {
    "method": "PUT",
    "upload_url": "https://.../uploads/user/12/20260519-abcdef.png?signature=...",
    "object_key": "uploads/user/12/20260519-abcdef.png",
    "public_url": "https://.../uploads/user/12/20260519-abcdef.png",
    "expires_in": 900,
    "content_type": "image/png"
  }
}

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Body

​
file_name
string
The original file name. The server will generate the object key based on the extension. It also works if omitted, but it is generally recommended to pass it explicitly.
​
content_type
string
The file MIME type, such as image/png, image/jpeg, or video/mp4.
​
expires_in
integer
The validity period of the pre-signed URL, in seconds. The server automatically constrains it between 60 and 3600.
​
prefix
string
The object key prefix. If not provided, uploads/user/{id} is used by default.

​
Response

​
success
boolean
Whether the request succeeded. /api/* endpoints use this field first to indicate the business result.
​
data.method
string
The upload method, currently fixed as PUT.
​
data.upload_url
string
The signed object storage upload URL.
​
data.public_url
string
The public URL that can be directly passed to image, video, and task endpoints after a successful upload.

​
Use Cases

​
Use it as a media URL after uploading

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

​
Notes

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.