Zum Hauptinhalt springen
POST
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.

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: MP3 (.mp3), WAV (.wav), M4A (.m4a)Standardmäßige maximale Dateigröße: 15MB. Größenlimits sind konfigurierbar. Maßgeblich sind die aktuelle Dienstkonfiguration und die Fehlermeldung bei Überschreitung.
Bei cURL --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 HTTP 400. Container- oder Framestruktur wird geprüft. Gefälschte Header und beschädigte Dateien werden abgelehnt. OGG, FLAC und AAC als roher ADTS-Stream werden nicht unterstützt.

Erfolgreiche Antwort

HTTP 200 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 audio.
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.

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 enthalten X-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 Objekt error auf oberster JSON-Ebene. Prüfen Sie HTTP-Status, error.type / error.code und error.message.

URLs nutzen und Dateien aufbewahren

72 Stunden ist das Standardzeitfenster für das Kontingent, keine Zusage zur Dateiaufbewahrung. Die Speicherrichtlinie bestimmt die Haltbarkeit. Originale behalten und URLs zeitnah für die Generierung nutzen; nicht von dauerhaft gültigen URLs ausgehen.

Weitere Upload-Endpunkte