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
}
}
Upload-Verwaltung
Video hochladen
Laden Sie MP4-, MOV- oder WebM-Videos hoch und erhalten Sie eine öffentliche URL für Generierungs-APIs. Standardlimit: 50MB pro Datei.
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
}
}
Referenzdateien hochladen und bei Erfolg direkt eine öffentliche URL erhalten; kein Polling erforderlich. Uploads sind kostenlos, setzen aber ein positives Kontoguthaben voraus. Die drei Endpunkte teilen ein Benutzerkontingent: standardmäßig insgesamt 2000 Dateien innerhalb von 72 Stunden.
Der Dokumentations-Playground unterstützt keine Dateiuploads. Verwenden Sie die cURL-, Python- oder JavaScript-Beispiele. Das JavaScript-Beispiel benötigt ein
<input type="file"> mit ausgewählter Datei.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
}
}
Authentifizierung
string
erforderlich
Verwenden Sie einen gültigen, aktivierten, nicht abgelaufenen APIMart API Key als
Bearer <token>. Das Konto darf nicht gesperrt sein und muss positives Guthaben haben. Ein ausgeschöpftes Kontingent des Keys verhindert Uploads nicht. Keys erhalten Sie unter API-Key-Verwaltung.Anfrageparameter
file
erforderlich
Senden Sie eine Datei einschließlich Dateinamen im Feld
file einer multipart/form-data-Anfrage. JSON, base64-Zeichenfolgen und Datei-URLs ersetzen den Dateiteil nicht. Andere Formularfelder werden ignoriert; bei mehreren file-Teilen wird nur der erste verarbeitet.Unterstützte Formate: MP4 (.mp4), MOV (.mov), WebM (.webm)Standardmäßige maximale Dateigröße: 50MB. Größenlimits sind konfigurierbar. Maßgeblich sind die aktuelle Dienstkonfiguration und die Fehlermeldung bei Überschreitung.--form, Python files oder JavaScript FormData erzeugt der Client Content-Type einschließlich Boundary automatisch. Setzen Sie diesen Header nicht manuell.
Dateiprüfung
Der Typ wird anhand des Inhalts erkannt, nicht anhand der Dateiendung oder des angegebenen MIME-Typs. Inhalt und Endpunkt müssen zusammenpassen. Umbenennen konvertiert keine Datei; ein falscher Typ führt zu HTTP400.
Die Containerstruktur wird geprüft. Gefälschte Header und beschädigte Container werden abgelehnt. Nur die unten aufgeführten Formate sind erlaubt; AVI oder MKV werden durch Umbenennen nicht unterstützt.
| Format | Erkannter MIME-Typ |
|---|---|
| MP4 (.mp4) | video/mp4 |
| MOV (.mov) | video/quicktime |
| WebM (.webm) | video/webm |
Erfolgreiche Antwort
HTTP200 liefert Dateiinformationen. url steht auf der obersten JSON-Ebene, ohne data-Hülle und ohne Generierungsaufgaben-ID.
string
Öffentliche Datei-URL für den passenden Referenzparameter der Generierungs-API. Modelle haben weiterhin eigene Format-, Größen-, Mengen- und Dauerlimits. Ein erfolgreicher Upload garantiert keine Modellkompatibilität.
string
Ursprünglicher Dateiname.
string
Vom Server aus dem Inhalt erkannter MIME-Typ, nicht der vom Client angegebene Wert.
string
Dateikategorie. Dieser Endpunkt liefert
video.integer
Tatsächliche Dateigröße in Byte.
integer
Uploadzeit als Unix-Zeitstempel in Sekunden.
object
Optionale Kontingentinformationen. Die Felder für begrenzte Benutzer stehen unten. Bei unbegrenztem Kontingent oder vorübergehend fehlenden Statistiken kann die Struktur abweichen.
| Feld | Beschreibung |
|---|---|
quota.limit | Maximale erfolgreiche Uploads dieses Benutzers im Zeitfenster; kann vom Standardwert 2000 abweichen. |
quota.used | Belegte Plätze im Fenster, einschließlich dieses erfolgreichen Uploads. |
quota.remaining | Anzahl der aktuell noch hochladbaren Dateien. |
quota.window_hours | Zeitfenster in Stunden, standardmäßig 72. |
quota.reset_at | Zeitpunkt, zu dem die älteste Gruppe aus dem Fenster fällt, in Unix-Sekunden. Dann werden einige Plätze frei; nicht zwingend das gesamte Kontingent. |
Gemeinsames Kontingent und Anfragelimits
Bilder, Videos und Audio teilen ein Kontingent pro Benutzer. Mehrere Keys desselben Benutzers erhöhen es nicht. Das Fenster verschiebt sich zur vollen Stunde und zählt standardmäßig erfolgreiche Uploads der letzten etwa 71–72 Stunden. Ungültige oder zu große Dateien sowie Speicherfehler verbrauchen kein Dateikontingent. Normale Antworten mit begrenztem Kontingent enthaltenX-Upload-Quota-Limit, X-Upload-Quota-Remaining und X-Upload-Quota-Reset, entsprechend limit, remaining und reset_at. Reset ist in Unix-Sekunden angegeben.
Unbegrenzte Benutzer erhalten quota: {"unlimited": true} ohne diese drei Header. Sind Statistiken vorübergehend nicht verfügbar, kann quota auch bei Erfolg fehlen. Fehlende Werte bedeuten weder null noch unbegrenzt; laden Sie deshalb nicht erneut hoch.
Ein ausgeschöpftes Dateikontingent liefert HTTP 429, error.type: rate_limit_exceeded, quota mit remaining: 0 und Retry-After. Warten Sie die angegebene Sekundenzahl. Unabhängig davon gilt ein Limit von 1000 Anfragen je Key in 60 Sekunden mit rate_limit_error.
Fehlerbehandlung
Fehler stehen im Objekterror auf oberster JSON-Ebene. Prüfen Sie HTTP-Status, error.type / error.code und error.message.
| HTTP | error.type | Ursache und Maßnahme |
|---|---|---|
| 400 | invalid_request_error | Fehlende Datei, kein multipart, leere Datei, falscher Typ, nicht unterstütztes Format oder beschädigter Inhalt. Datei oder Endpunkt korrigieren. |
| 401 / 403 | — | Ungültiger oder deaktivierter Key beziehungsweise gesperrtes Konto. Authentifizierung und Kontostatus prüfen. |
| 402 | insufficient_user_quota | Kontoguthaben nicht positiv oder Key abgelaufen. Guthaben aufladen oder gültigen Key verwenden. Diese Bedingungen gelten auch für kostenlose Uploads. |
| 413 | invalid_request_error | Dateigröße überschreitet das Limit ihres Typs. Komprimieren oder verkleinern; aktuellen Grenzwert der Fehlermeldung entnehmen. |
| 429 | rate_limit_exceeded | Gemeinsames Dateikontingent erschöpft. quota und Retry-After auswerten und auf freie Plätze warten. |
| 429 | rate_limit_error | Zu viele Anfragen des Keys. Frequenz senken und mit wachsendem Abstand wiederholen. |
| 503 | server_error | Zu viele gleichzeitige Video-/Audio-Uploads oder Speicher vorübergehend nicht verfügbar. Später erneut versuchen. |
| 500 | server_error | Datei konnte nicht gespeichert werden. Später erneut versuchen. |