curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Управление загрузками
Загрузка видео
Загрузите MP4, MOV или WebM и получите публичный URL для API генерации. Лимит по умолчанию: 50MB на файл.
POST
/
v1
/
uploads
/
videos
curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Загрузите референсный файл и сразу получите публичный URL при успехе; опрос задачи не нужен. Загрузка бесплатна, но баланс аккаунта должен быть положительным. Три endpoint используют общую квоту пользователя: по умолчанию 2000 файлов за 72 часа.
Playground документации не поддерживает загрузку файлов. Используйте примеры cURL, Python или JavaScript. Для JavaScript нужен элемент
<input type="file"> с выбранным файлом.curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Аутентификация
string
обязательно
Используйте действующий, включённый и не просроченный APIMart API Key в формате
Bearer <token>. Аккаунт не должен быть заблокирован, баланс должен быть положительным. Исчерпание собственной квоты Key не мешает загрузке. Получить Key можно в управлении API Keys.Параметры запроса
file
обязательно
Передайте один файл с именем в поле
file запроса multipart/form-data. Не заменяйте файловую часть JSON, строкой base64 или URL. Другие поля формы игнорируются; если частей file несколько, обрабатывается только первая.Поддерживаемые форматы: MP4 (.mp4), MOV (.mov), WebM (.webm)Максимальный размер по умолчанию: 50MB. Лимиты размера настраиваются. Ориентируйтесь на текущую конфигурацию и значение в ошибке превышения размера.--form, Python files или JavaScript FormData клиент сам создаёт Content-Type с boundary. Не задавайте этот заголовок вручную.
Проверка файлов
Тип определяется по содержимому, а не расширению или заявленному MIME. Содержимое должно соответствовать endpoint. Переименование не меняет формат; несовпадение типа возвращает HTTP400.
Проверяется структура контейнера. Поддельные заголовки и повреждённые контейнеры отклоняются. Поддерживаются только форматы ниже; переименование AVI, MKV и других не помогает.
| Формат | Определённый MIME-тип |
|---|---|
| MP4 (.mp4) | video/mp4 |
| MOV (.mov) | video/quicktime |
| WebM (.webm) | video/webm |
Успешный ответ
HTTP200 возвращает сведения о файле. url находится в корне JSON, без обёртки data и без ID задачи генерации.
string
Публичный URL для соответствующего параметра референса в API генерации. У моделей остаются собственные ограничения формата, размера, количества и длительности. Успешная загрузка не гарантирует совместимость с моделью.
string
Исходное имя файла.
string
MIME-тип, определённый сервером по содержимому, а не значение клиента.
string
Категория файла. Этот endpoint возвращает
video.integer
Фактический размер в байтах.
integer
Время загрузки в секундах Unix.
object
Необязательные сведения о квоте. Поля ограниченного пользователя перечислены ниже. При отсутствии лимита или временной недоступности статистики структура может отличаться.
| Поле | Описание |
|---|---|
quota.limit | Максимум успешных загрузок этого пользователя за окно; может отличаться от 2000. |
quota.used | Использованные места в окне, включая текущую успешную загрузку. |
quota.remaining | Число файлов, которые ещё можно загрузить сейчас. |
quota.window_hours | Размер окна в часах; по умолчанию 72. |
quota.reset_at | Время выхода самой старой группы записей из окна, в секундах Unix. Освободится часть мест, а не обязательно вся квота сразу. |
Общая квота и частота запросов
Изображения, видео и аудио используют общую квоту пользователя. Несколько Keys одного пользователя не увеличивают её. Окно сдвигается каждый полный час и по умолчанию учитывает успехи за последние примерно 71–72 часа. Некорректные, слишком большие и не сохранённые файлы не расходуют файловую квоту. Обычные ограниченные ответы содержатX-Upload-Quota-Limit, X-Upload-Quota-Remaining и X-Upload-Quota-Reset, соответствующие limit, remaining и reset_at. Reset указан в секундах Unix.
Пользователи без лимита получают quota: {"unlimited": true} без этих трёх заголовков. При временно недоступной статистике успешный ответ может не содержать quota. Отсутствие данных не означает нулевую или неограниченную квоту; не загружайте повторно только по этой причине.
Исчерпанная файловая квота возвращает HTTP 429, error.type: rate_limit_exceeded, quota с remaining: 0 и Retry-After. Подождите указанное число секунд. Отдельно действует ограничение 1000 запросов на Key за 60 секунд с типом rate_limit_error.
Обработка ошибок
Ошибки находятся в корневом объектеerror. Проверяйте HTTP-статус, error.type / error.code и error.message.
| HTTP | error.type | Причина и действие |
|---|---|---|
| 400 | invalid_request_error | Нет файла, запрос не multipart, пустой файл, неправильный тип, неподдерживаемый формат или повреждение. Исправьте файл либо endpoint. |
| 401 / 403 | — | Недействующий или отключённый Key либо заблокированный аккаунт. Проверьте авторизацию и статус аккаунта. |
| 402 | insufficient_user_quota | Неположительный баланс или просроченный Key. Пополните баланс либо используйте действующий Key. Бесплатная загрузка также требует соблюдения этих условий. |
| 413 | invalid_request_error | Файл превышает лимит своего типа. Сожмите или уменьшите его; текущий предел указан в ошибке. |
| 429 | rate_limit_exceeded | Общая файловая квота исчерпана. Прочитайте quota и Retry-After и дождитесь свободных мест. |
| 429 | rate_limit_error | Слишком частые запросы Key. Снизьте частоту и повторяйте с задержкой. |
| 503 | server_error | Слишком много одновременных загрузок видео/аудио или хранилище временно недоступно. Повторите позже. |
| 500 | server_error | Не удалось записать файл. Повторите позже. |