Upload File

curl --request PUT \
  --url https://octopusx.ai/v1/file/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "headers": {
    "Content-Type": "<string>"
  },
  "params": {}
}
'

import requests

url = "https://octopusx.ai/v1/file/upload"

payload = {
    "headers": { "Content-Type": "<string>" },
    "params": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({headers: {'Content-Type': '<string>'}, params: {}})
};

fetch('https://octopusx.ai/v1/file/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://octopusx.ai/v1/file/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'headers' => [
        'Content-Type' => '<string>'
    ],
    'params' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://octopusx.ai/v1/file/upload"

	payload := strings.NewReader("{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://octopusx.ai/v1/file/upload")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octopusx.ai/v1/file/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "",
    "message": "oss storage is not configured",
    "type": "aix_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 7ca08841-73ab-11f1-92b8-1a9776f84c80)",
    "type": "aix_api_error"
  }
}

PUT

https://octopusx.ai

file

upload

Upload File

curl --request PUT \
  --url https://octopusx.ai/v1/file/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "headers": {
    "Content-Type": "<string>"
  },
  "params": {}
}
'

import requests

url = "https://octopusx.ai/v1/file/upload"

payload = {
    "headers": { "Content-Type": "<string>" },
    "params": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({headers: {'Content-Type': '<string>'}, params: {}})
};

fetch('https://octopusx.ai/v1/file/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://octopusx.ai/v1/file/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'headers' => [
        'Content-Type' => '<string>'
    ],
    'params' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://octopusx.ai/v1/file/upload"

	payload := strings.NewReader("{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://octopusx.ai/v1/file/upload")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octopusx.ai/v1/file/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"headers\": {\n    \"Content-Type\": \"<string>\"\n  },\n  \"params\": {}\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "",
    "message": "oss storage is not configured",
    "type": "aix_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 7ca08841-73ab-11f1-92b8-1a9776f84c80)",
    "type": "aix_api_error"
  }
}

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

PUT /v1/file/upload

Request Example

Upload Image

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": {}
  }'

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

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());

Upload Video

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": {}
  }'

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

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());

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.

# 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

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

{
  "error": {
    "code": "",
    "message": "oss storage is not configured",
    "type": "aix_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 7ca08841-73ab-11f1-92b8-1a9776f84c80)",
    "type": "aix_api_error"
  }
}

Authentication

Authorization: Bearer YOUR_API_KEY

Body

headers

object

Custom headers for the upload request.

Content-Type

string

The file MIME type, such as image/png, image/jpeg, or video/mp4.

params

object

Additional query parameters for the upload URL. Can be an empty object {} if no extra parameters are needed.

Response

download_url

string

The public URL that can be directly passed to image, video, and task endpoints after a successful upload.

expire

integer

The expiration time of the pre-signed URL in seconds.

method

string

The upload method, currently fixed as PUT.

upload_url

string

The signed object storage upload URL.

Use Cases

Use it as a media URL after uploading

Call /v1/file/upload to obtain upload_url and download_url.
Upload the file by sending a PUT request to upload_url.
Pass download_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.

Upload Management Overview Task Management Overview

Overview

Text Models

Image Models

Video Models

Uploads

Tasks

Account

Upload File

Upload File

Method and Path

Request Example

Upload Image

Upload Video

Upload File to the Presigned URL

Response Example

Authentication

Body

Response

Use Cases

Use it as a media URL after uploading

Notes

​Upload File

​Method and Path

​Request Example

​Upload Image

​Upload Video

​Upload File to the Presigned URL

​Response Example

​Authentication

​Body

​Response

​Use Cases

​Use it as a media URL after uploading

​Notes

​Related APIs

Upload File

Method and Path

Request Example

Upload Image

Upload Video

Upload File to the Presigned URL

Response Example

Authentication

Body

Response

Use Cases

Use it as a media URL after uploading

Notes

Related APIs