VanceAI Open API documentation

Die API stellt die Verarbeitungs-Engine von VanceAI über eine kleine, stabile Gruppe von REST-Endpunkten bereit. Sie senden einen Job mit einer Datei oder URL, fragen den Status ab und laden das Ergebnis herunter. Bild- und Video-Tools liegen unter derselben Ressource /v1/jobs — das gewählte tool bestimmt Medientyp und Operation.

Alle API-Anfragen gehen an:

https://cloud-vanceai.vanceai.com/api/v1

Jede Antwort ist application/json. Alle Anfragen müssen mit einem API-Schlüssel authentifiziert werden — siehe Authentifizierung.

Die API ist vollständig asynchron und basiert auf drei Schritten:

POST /v1/jobs            → returns a job_id immediately (status: "queued")
GET  /v1/jobs/{id}       → poll until status is "succeeded" or "failed"
GET  /v1/jobs/{id}/result → fetch a fresh, never-expiring download link

Ein POST blockiert nie während Upload oder Verarbeitung. Es validiert Ihre Anfrage, reserviert den Job und gibt in Millisekunden eine job_id zurück. Ein Hintergrund-Worker übernimmt anschließend Upload, Verarbeitung und Ergebnis — so funktionieren selbst mehrere Gigabyte große Videos ohne HTTP-Timeouts.

• Authentifizierung — API-Schlüssel beziehen und verwenden.
• Schnellstart — Ihr erster Job in wenigen Minuten.
• Jobs & Lebenszyklus — die vollständige Endpunkt-Referenz.

Schlüssel sehen so aus und beginnen immer mit dem Präfix sk_live_:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Erstellen und widerrufen Sie Schlüssel über Ihr VanceAI-Konto-Dashboard. Der vollständige Schlüssel wird nur einmal bei der Erstellung angezeigt — bewahren Sie ihn sicher auf. Bei Verlust widerrufen Sie den Schlüssel und erstellen einen neuen. Siehe API-Schlüssel verwalten.

Senden Sie Ihren Schlüssel bei jeder Anfrage als Bearer-Token im Header Authorization:

Authorization: Bearer sk_live_a1b2c3d4e5f6...

Zum Beispiel, um Ihr Credit-Guthaben abzufragen:

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

Ein fehlender, ungültiger oder widerrufener Schlüssel gibt 401 mit einem stabilen Fehlercode zurück:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been disabled.",
    "type": "auth"
  }
}

Die vollständige Liste der Codes und deren Behandlung finden Sie unter Fehler.

Senden Sie das Bild als Multipart-Formulardaten zusammen mit dem tool und seiner config. Sie können eine Datei direkt hochladen (bis zu 200 MB) oder stattdessen eine öffentliche image_url übergeben.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}' \
  -F output_format=jpg

Oder senden Sie eine URL mit JSON-Body:

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "tool": "upscale",
    "config": { "scale": 4, "face_enhance": true },
    "output_format": "jpg"
  }'

Die Antwort liefert sofort eine job_id und den Status queued:

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

Fragen Sie GET /v1/jobs/{job_id} ab, bis status zu succeeded (oder failed) wird. Bei Bildern reicht ein Polling alle ~2 Sekunden.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c... \
  -H "Authorization: Bearer sk_live_..."

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

Die result_url aus Schritt 2 ist ein signierter Link, der irgendwann abläuft. Für einen Link, der nie abläuft, rufen Sie den Result-Endpunkt auf, der bei Bedarf neu signiert:

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o upscaled.jpg

Jeder Job durchläuft diese Status:

Während processing präzisiert das Feld phase: uploading → syncing → processing. Der numerische progress (0–100) ist erst aussagekräftig, wenn phase processing ist; während Upload/Sync bleibt er 0. Bei großen Videos kann die Upload-Phase Minuten dauern — beurteilen Sie „hängt es?" anhand von phase, nicht progress.

Videos werden in zwei Schritten direkt in den Speicher hochgeladen, sodass die Bytes nie die API durchlaufen und mehrere Gigabyte große Dateien nicht durch die Anfragegröße begrenzt sind. Rufen Sie zuerst POST /v1/uploads für eine einmalige vorsignierte Upload-URL auf und führen Sie dann ein PUT der Datei dorthin aus. Bilder überspringen dies — laden Sie sie beim Erstellen des Jobs direkt hoch (siehe unten). Direkter Multipart-Upload von Videos wird nicht unterstützt; source_url wird weiterhin als Alternative akzeptiert.

Anfrageparameter

Beispiel

curl https://cloud-vanceai.vanceai.com/api/v1/uploads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "clip.mp4",
    "file_size": 734003200,
    "content_type": "video/mp4"
  }'

Antwort — 201 Created

{
  "upload_id": "upl_8f3b1c2a...",
  "put_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "expires_at": "2026-06-13T08:30:00Z",
  "max_bytes": 5261334937
}

put_url ist eine vorsignierte, 24 Stunden gültige URL. Laden Sie die rohen Bytes mit einem einzigen PUT dorthin — ohne Auth-Header, nur die Datei:

curl -X PUT --upload-file clip.mp4 \
  -H "Content-Type: video/mp4" \
  "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=..."

Sobald das PUT erfolgreich ist, erstellen Sie den Job, indem Sie die upload_id statt einer Datei übergeben — siehe Job erstellen. Jede upload_id ist einmalig verwendbar.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_8f3b1c2a...",
    "tool": "video_upscale",
    "config": { "scale": 2, "codec": "h264" }
  }'

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "video_upscale",
  "media": "video",
  "credits_estimated": 0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

Wie Sie das Medium bereitstellen, hängt vom Typ ab. Bilder: direkter Datei-Upload (Multipart) oder eine öffentliche URL. Videos: eine upload_id aus dem Upload-Schritt oben oder eine öffentliche source_url. Das tool wählt Medientyp und Operation.

Anfrageparameter

Idempotenz

Übergeben Sie einen Idempotency-Key-Header, um eine Erstellungsanfrage sicher zu wiederholen, ohne den Job zu duplizieren. Siehe Ratenlimits & Idempotenz.

Beispiel

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a-unique-string" \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}'

Antwort — 202 Accepted

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

Die Antwort kommt zurück, bevor Credits berechnet werden (credits_charged ist 0). credits_estimated ist eine Vorab-Schätzung; die maßgebliche Abbuchung erscheint, sobald der Job processing erreicht. Siehe Credits & Abrechnung.

Gibt den aktuellen Status eines Jobs zurück. Fragen Sie ab, bis der Job einen Endstatus erreicht.

Antwort — 200 (processing)

{
  "job_id": "job_3f2a9c...",
  "status": "processing",
  "phase": "uploading",
  "progress": 0,
  "tool": "video_upscale",
  "media": "video",
  "result_url": null,
  "result": null,
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": null
}

Antwort — 200 (succeeded)

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

Die Form von result ist { width, height, size } für Bilder und { width, height, duration, size, codec } für Video. Die result_url ist ein signierter Link, der abläuft — für einen dauerhaften Link nutzen Sie den Result-Endpunkt unten.

Leitet (302) zu einer frisch signierten Result-URL um — bei jedem Aufruf neu signiert, sodass der Link nie veraltet. Verwenden Sie dies zum Herunterladen der Ausgabe, statt result_url zwischenzuspeichern.

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o result.jpg

Bricht einen Job ab, der noch queued oder processing ist. Vor allem für lange Video-Jobs nützlich. Reservierte Credits werden vollständig erstattet.

{ "job_id": "job_3f2a9c...", "status": "canceled" }

Ein Job, der bereits succeeded, failed oder canceled ist, gibt 409 not_cancelable zurück.

Löscht einen Job-Datensatz und sein zugehöriges Ergebnis — nützlich zum Bereinigen verarbeiteter Assets aus Datenschutz- oder Compliance-Gründen. Läuft der Job noch, wird er zuvor abgebrochen (und Credits erstattet).

{ "job_id": "job_3f2a9c...", "deleted": true }

• Das Löschen eines bereits gelöschten Jobs gibt weiterhin 200 { "deleted": true } zurück (idempotent).
• Sie können nur Jobs Ihres eigenen Kontos löschen; andere geben 404 job_not_found zurück.

Bild-Tools nehmen ein config-Objekt entgegen. Die Option face_enhance (Boolean) ist bei den meisten Tools optional. Setzen Sie output_format in der Anfrage, um jpg / png / webp zu wählen.

{ "scale": 4, "face_enhance": true }

Video-Tools werden Ende-zu-Ende verarbeitet (kein Vorschau-Clip-Modus in v1). Die Optionen quality (high / medium / low) und codec (h264 / h265) gelten nur für video_hdr und video_face_enhance. Bei video_upscale wird die Ausgabe-Kodierung von der Upscaler-Engine bestimmt, daher werden quality / codec nicht verwendet (das Senden hat keine Wirkung).

{ "scale": 2 }

Die Anforderung eines Tools, das nicht existiert — oder noch nicht verfügbar ist (die Video-Operationen translate, colorize und subtitle sind nicht in v1) — gibt 400 unsupported_tool zurück.

Der Credit-Fluss über die Lebensdauer eines Jobs:

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_..."

{ "balance": 999.8, "used": 234.2, "frozen": 12.5 }

Credit-Beträge sind Dezimalzahlen (manche Operationen kosten einen Bruchteil eines Credits).

Jeder API-Schlüssel hat ein Anfrageratenlimit. Bei Überschreitung wird 429 rate_limited mit Headern zu Ihrem aktuellen Fenster zurückgegeben:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718093460

Antworten können auch einen Retry-After-Header (Sekunden) enthalten — beachten Sie ihn vor dem erneuten Versuch.

Da ein einzelner Video-Job viele Minuten dauern kann, reicht die Anfragerate allein nicht. Es gibt zudem eine Obergrenze für die Anzahl gleichzeitig laufender Jobs Ihres Kontos (queued oder processing) — bei Video meist niedriger als bei Bildern.

Senden über die Obergrenze hinaus gibt 429 concurrency_limit_exceeded zurück. Warten Sie, bis einige laufende Jobs fertig sind, und versuchen Sie es erneut. Die Zählung erfolgt pro Konto, daher umgeht das Verteilen auf mehrere Schlüssel sie nicht.

v1 hat keine Webhooks, daher fragen Sie GET /v1/jobs/{id} ab. Um die API nicht zu überlasten:

• Empfohlenes Intervall: etwa 2 s für Bilder, 5–10 s für Video.
• Beachten Sie den Retry-After-Header, falls vorhanden — er ist ein Hinweis für die nächste Abfrage.
• Beenden Sie das Polling, sobald der Job einen Endstatus erreicht (succeeded / failed / canceled).

Netzwerkaussetzer können Sie im Unklaren lassen, ob ein POST /v1/jobs erfolgreich war. Senden Sie zum sicheren Wiederholen einen eindeutigen Idempotency-Key-Header:

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f3b1c2a-...-unique" \
  -F [email protected] \
  -F tool=upscale

• Das erneute Senden desselben Schlüssels gibt den ursprünglichen Job zurück — kein Duplikat, keine doppelte Abbuchung.
• Erzeugen Sie pro logischer Anfrage einen neuen Schlüssel (eine UUID eignet sich gut).
• Die Wiederverwendung eines Schlüssels mit anderem tool oder config gibt 409 idempotency_conflict zurück.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for this operation.",
    "type": "billing"
  }
}

code ist ein stabiler String — verzweigen Sie darauf. message ist menschenlesbar und kann sich ändern. type ist die grobe Kategorie: auth, billing, validation, processing, rate_limit oder server.

Wird eine Anfrage direkt abgelehnt, erhalten Sie den passenden HTTP-Status und einen error-Body:

Wenn ein Job *asynchron* fehlschlägt, gibt das Abfragen von GET /v1/jobs/{id} HTTP 200 mit status: "failed" und einem Code in error.code zurück. Erwarten Sie keinen 5xx für einen fehlgeschlagenen Job — die Abfrage selbst war erfolgreich.

Erstellen Sie in Ihrem Dashboard einen neuen Schlüssel und geben Sie ihm einen erkennbaren Namen (z. B. my-app-prod). Das vollständige Geheimnis — beginnend mit sk_live_ — wird nur einmal direkt nach der Erstellung angezeigt.

Das Dashboard listet Ihre Schlüssel nach Name, Status, einem kurzen Präfix (z. B. sk_live_a1b2) zur Identifizierung und dem Zeitpunkt der letzten Verwendung auf. Das vollständige Geheimnis wird nie wieder angezeigt — nur das Präfix.

Das Deaktivieren eines Schlüssels wirkt sofort — jede weitere Anfrage damit gibt 401 invalid_api_key zurück.

• Der Widerruf ist dauerhaft. Es gibt keine Reaktivierung; erstellen Sie stattdessen einen neuen Schlüssel.
• Sie können nur Schlüssel verwalten, die zu Ihrem eigenen Konto gehören.

Mehrere aktive Schlüssel können nebeneinander existieren, was die Rotation nahtlos macht: Erstellen Sie einen neuen Schlüssel, stellen Sie Ihre Anwendung darauf um, bestätigen Sie, dass der Traffic migriert ist, und widerrufen Sie dann den alten Schlüssel. Ein eigener Schlüssel pro Anwendung oder Umgebung begrenzt den Schaden bei einem Leck.

Die erste stabile Version umfasst:

• Einheitliche Jobs-API für Bild und Video — POST /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/result, POST /v1/jobs/{id}/cancel, DELETE /v1/jobs/{id} und GET /v1/credits.
• 8 Bild-Tools und 1 Video-Tool (Hochskalieren).
• Große Dateien: Bild-Direktuploads bis 200 MB; Videos über zweistufigen Direktupload; beliebige Medien über source_url (SSRF-geschützt).
• Asynchrone Verarbeitung mit Vorab-Credit-Prüfung und Hintergrund-Worker.
• Credit-Reservierungen mit voller Erstattung bei Fehlschlag oder Abbruch.
• Stabile Fehlercodes, Idempotency-Key-Unterstützung, Ratenlimits pro Schlüssel und Parallelitätslimits pro Konto.
• Zweistufiger Video-Direktupload — POST /v1/uploads stellt eine vorsignierte URL aus, sodass Videos direkt in den Speicher hochgeladen werden (ein einzelnes PUT bis zu ~4,9 GB) und das Anfragegrößenlimit umgehen.
• Genaue Video-Abrechnung — der Server misst Auflösung, Dauer und Bildrate mit ffprobe und prüft die Ausgabeauflösung vorab gegen das Engine-Limit.