上传文件
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"
}
}
上传管理
上传文件
调用 /v1/file/upload 生成预签名上传地址,再把返回的 download_url 传给接受公网素材 URL 的接口。
PUT
https://octopusx.ai
/
v1
/
file
/
upload
上传文件
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 地址。客户端拿到地址后再自行上传文件。
- 适合图片、视频和其他媒体素材的预上传。
- 使用 API Key 认证。
- 默认过期时间为
900秒,最短60秒,最长3600秒。
方法与路径
PUT /v1/file/upload
请求示例
上传图片
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());
上传视频
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_url 后,对目标地址发起 PUT 请求上传文件本体。Content-Type 须与请求预签名地址时传入的值一致。
# 上传视频(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
响应示例
{
"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"
}
}
认证
Authorization: Bearer YOUR_API_KEY
Body
上传 URL 的附加查询参数。如果不需要额外参数,可以传空对象
{}。Response
上传成功后可直接传给图像、视频和任务接口的公网 URL。
预签名 URL 的过期时间,单位秒。
上传方法,当前固定为
PUT。带签名的对象存储上传地址。
使用场景
上传后再用于素材 URL 接口
- 调用
/v1/file/upload取得upload_url与download_url。 - 对
upload_url发起PUT上传文件。 - 在接受公网素材 URL 的接口中把
download_url作为输入字段传入。
注意事项
这个接口只负责签发上传地址,不会替你上传文件本身。真正的文件上传需要客户端对
upload_url 再发一次 PUT 请求。相关接口
⌘I