Загрузить файл
Загрузка файла в хранилище
POST
/
v1
/
storage
/
upload
Загрузить файл
curl --request POST \
--url https://speshu.ai/api/v1/storage/upload \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=<string>' \
--form externalUserId=user_123 \
--form storagePolicy=TEMP_UPLOAD \
--form 0.file='@example-file'import requests
url = "https://speshu.ai/api/v1/storage/upload"
files = { "0.file": ("example-file", open("example-file", "rb")) }
payload = {
"file": "<string>",
"externalUserId": "user_123",
"storagePolicy": "TEMP_UPLOAD"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', '<string>');
form.append('externalUserId', 'user_123');
form.append('storagePolicy', 'TEMP_UPLOAD');
form.append('0.file', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://speshu.ai/api/v1/storage/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://speshu.ai/api/v1/storage/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$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://speshu.ai/api/v1/storage/upload"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://speshu.ai/api/v1/storage/upload")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://speshu.ai/api/v1/storage/upload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "file_123abc",
"fileType": "IMAGE",
"mimeType": "image/jpeg",
"source": "USER_UPLOAD",
"storagePolicy": "TEMP_UPLOAD",
"url": "https://s3.speshu.ai/f/211837/2026/01/t_c2446f3cf93ac9f5.png",
"size": 154832,
"createdAt": "2025-01-03T12:00:00.000Z",
"updatedAt": "2025-01-03T12:00:00.000Z",
"externalUserId": "external_user_456",
"expiresAt": "2025-01-03T14:00:00.000Z"
}Способы загрузки
Storage API поддерживает два способа загрузки файлов:- Multipart/form-data — загрузка файла напрямую
- Base64 — загрузка закодированного файла в JSON
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
file | binary | Да (multipart) | Файл для загрузки (multipart/form-data) |
base64 | string | Да (JSON) | Файл в формате base64 |
mimeType | string | Нет | MIME-тип файла (определяется автоматически при multipart) |
externalUserId | string | Нет | Внешний идентификатор пользователя (макс. 128 символов) |
storagePolicy | string | Нет | Политика хранения (по умолчанию TEMP_UPLOAD) |
Политики хранения
| Политика | Срок хранения | Описание |
|---|---|---|
TEMP_UPLOAD | 24 часа | Временная загрузка пользователя (по умолчанию) |
PERMANENT | Бессрочно | Постоянное хранение |
TEMP_GENERATION (7 дней) применяется автоматически к результатам AI генераций через Media API и не может быть задана вручную.
Примеры
curl -X POST "https://speshu.ai/api/v1/storage/upload" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.png" \
-F "storagePolicy=PERMANENT"
curl -X POST "https://speshu.ai/api/v1/storage/upload" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"base64": "iVBORw0KGgoAAAANSUhEUg...",
"mimeType": "image/png",
"storagePolicy": "PERMANENT"
}'
Ответ (200)
{
"id": "file_abc123",
"fileType": "IMAGE",
"mimeType": "image/png",
"source": "USER_UPLOAD",
"storagePolicy": "PERMANENT",
"url": "https://cdn.speshu.ai/files/file_abc123.png",
"size": 245760,
"externalUserId": null,
"expiresAt": null,
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-15T10:30:00Z"
}
Авторизации
API ключ передаётся в заголовке: Authorization: Bearer <SPESHU_AI_API_KEY>
Тело
multipart/form-dataapplication/json
Ответ
200 - application/json
ID файла
Пример:
"file_123abc"
Тип файла (IMAGE, VIDEO, AUDIO)
Пример:
"IMAGE"
MIME-тип файла
Пример:
"image/jpeg"
Источник файла (USER_UPLOAD, AI_GENERATION)
Пример:
"USER_UPLOAD"
Политика хранения (TEMP_UPLOAD, TEMP_GENERATION, PERMANENT)
Пример:
"TEMP_UPLOAD"
URL файла
Пример:
"https://s3.speshu.ai/f/211837/2026/01/t_c2446f3cf93ac9f5.png"
Размер файла в байтах
Пример:
154832
Дата создания
Пример:
"2025-01-03T12:00:00.000Z"
Дата обновления
Пример:
"2025-01-03T12:00:00.000Z"
ID внешнего пользователя клиента (для группировки файлов)
Пример:
"external_user_456"
Дата истечения срока действия файла
Пример:
"2025-01-03T14:00:00.000Z"
⌘I
Загрузить файл
curl --request POST \
--url https://speshu.ai/api/v1/storage/upload \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=<string>' \
--form externalUserId=user_123 \
--form storagePolicy=TEMP_UPLOAD \
--form 0.file='@example-file'import requests
url = "https://speshu.ai/api/v1/storage/upload"
files = { "0.file": ("example-file", open("example-file", "rb")) }
payload = {
"file": "<string>",
"externalUserId": "user_123",
"storagePolicy": "TEMP_UPLOAD"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', '<string>');
form.append('externalUserId', 'user_123');
form.append('storagePolicy', 'TEMP_UPLOAD');
form.append('0.file', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://speshu.ai/api/v1/storage/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://speshu.ai/api/v1/storage/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$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://speshu.ai/api/v1/storage/upload"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://speshu.ai/api/v1/storage/upload")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://speshu.ai/api/v1/storage/upload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"externalUserId\"\r\n\r\nuser_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"storagePolicy\"\r\n\r\nTEMP_UPLOAD\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "file_123abc",
"fileType": "IMAGE",
"mimeType": "image/jpeg",
"source": "USER_UPLOAD",
"storagePolicy": "TEMP_UPLOAD",
"url": "https://s3.speshu.ai/f/211837/2026/01/t_c2446f3cf93ac9f5.png",
"size": 154832,
"createdAt": "2025-01-03T12:00:00.000Z",
"updatedAt": "2025-01-03T12:00:00.000Z",
"externalUserId": "external_user_456",
"expiresAt": "2025-01-03T14:00:00.000Z"
}