Geprüft am 2026-11-11 · API-Version 2026-11-09 · Markdown lesen
AiVideoEditor-API-Quickstart
Basis-URL: https://<your-app-host>/api/v1 (lokale Entwicklung: http://localhost:3006/api/v1).
Authentifizierung
Erstelle einen Produktkey unter Developers in der Arbeitsbereichs-Navigation (/app/developers). Der Klartext-Key
(pk_v1_…) wird genau einmal angezeigt; gespeichert werden nur ein Hash und ein kurzer Präfix.
Sende ihn als Bearer-Token:
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
Keys tragen explizite Scopes (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) und eine optionale
Konto-Zulassungsliste. Ein Draft-only-Key lässt posts:publish weg und kann daher
nicht veröffentlichen, planen, abbrechen oder wiederholen. Keys können niemals andere Keys
erstellen oder die Abrechnung ändern. Das Widerrufen eines Keys pausiert seine ungesendeten
Jobs als requires_action: nichts wird gelöscht, und die Widerrufs-UI zeigt zuerst die Anzahl
der betroffenen ausstehenden Jobs an.
Grundregeln
- Jede Mutation erfordert einen
Idempotency-Key-Header. Gleicher Key + gleicher Body → dasselbe aufgezeichnete Ergebnis (gleiche Zustellungs-IDs). Gleicher Key + anderer Body →409 idempotency_conflict. - Bearbeitungen und Planung erfordern
expectedVersion; eine veraltete Version liefert409 revision_conflictmit der aktuellen Version inerror.details.currentVersion. 202von publish/schedule bedeutet zur Zustellung angenommen, nie „veröffentlicht“. Verfolge Ergebnisse mitGET /posts/{id}, Kunden-Webhooks oder begrenztem Polling.- Rate-Limits sind technische Geschwindigkeitsbegrenzungen pro Arbeitsbereich (60/120/240
Anfragen/Min je nach Plan;
429+Retry-After). Es gibt kein Anfrage- oder Posting-Kontingent: Posten ist auf jedem Bezahlplan unbegrenzt. - Fehler verwenden den normalisierten Umschlag:
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
End-to-End: Entwurf → validieren → veröffentlichen → beobachten
Das Beispiel erfordert Bash, curl, jq, Node 22+, einen aktiven Arbeitsbereich,
eine verbundene Facebook-Seite oder ein verbundenes LinkedIn-Ziel und einen Key mit
accounts:read, posts:read, posts:write und posts:publish. Setze
ACCOUNT_ID auf ein erlaubtes Ziel aus /accounts; prüfe seine Unterstützung des Textformats
in /capabilities. Das Ausführen des Publish-Befehls veröffentlicht echte Inhalte.
set -euo pipefail
BASE="${PUBLISHER_API_URL:?Set the AiVideoEditor origin}/api/v1"
AUTH="Authorization: Bearer ${PUBLISHER_KEY:?Set the product key}"
JSON="Content-Type: application/json"
new_key() { node -e 'console.log(require("node:crypto").randomUUID())'; }
curl --fail-with-body -sS -H "$AUTH" "$BASE/accounts"
curl --fail-with-body -sS -H "$AUTH" "$BASE/capabilities"
: "${ACCOUNT_ID:?Choose a permitted text destination from the responses above}"
# Save this key and body; reuse both if the connection fails ambiguously.
CREATE_KEY=$(new_key)
DRAFT_BODY=$(jq -n --arg account "$ACCOUNT_ID" '{caption:"A new update from our team.",mediaIds:[],brandFolderId:null,destinations:[{accountId:$account,format:"text"}]}')
DRAFT=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
-H "Idempotency-Key: $CREATE_KEY" -H "$JSON" \
"$BASE/posts" -d "$DRAFT_BODY")
POST_ID=$(jq -er '.post.postId' <<<"$DRAFT")
VERSION=$(jq -er '.post.version' <<<"$DRAFT")
VALIDATION=$(curl --fail-with-body -sS -X POST -H "$AUTH" "$BASE/posts/$POST_ID/validate")
printf '%s\n' "$VALIDATION"
jq -e '.validation.valid == true' <<<"$VALIDATION" >/dev/null
# 202 means accepted. Keep this key for an identical retry after a timeout.
PUBLISH_KEY=$(new_key)
ACCEPTED=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
-H "Idempotency-Key: $PUBLISH_KEY" "$BASE/posts/$POST_ID/publish")
printf '%s\n' "$ACCEPTED"
curl --fail-with-body -sS -H "$AUTH" "$BASE/posts/$POST_ID"
Für Bild-/Videoziele lade zuerst Medien hoch und finalisiere sie,
verwende dann die zurückgegebenen Asset-IDs in mediaIds und ein berechtigtes Zielformat.
Beobachte einzelne Zustellungs-IDs aus der angenommenen Antwort; verwende Webhooks oder ein
begrenztes Status-Polling mit Backoff. Ein einzelner sofortiger Statusabruf kann noch ausstehend sein.
Planen statt veröffentlichen
Verwende dies an einem Entwurf statt des Publish-Schritts oben. Rufe seine aktuelle Version nach jeder Bearbeitung erneut ab. Dies berechnet einen zukünftigen Zeitpunkt, statt ein Beispieldatum zu verwenden, das ablaufen würde.
SCHEDULED_AT=$(node -e 'console.log(new Date(Date.now()+86400000).toISOString())')
SCHEDULE_BODY=$(jq -n --arg at "$SCHEDULED_AT" --argjson version "$VERSION" \
'{scheduledAt:$at,timezone:"America/Indiana/Indianapolis",expectedVersion:$version}')
SCHEDULE_KEY=$(new_key)
curl --fail-with-body -sS -X POST -H "$AUTH" -H "Idempotency-Key: $SCHEDULE_KEY" \
-H "$JSON" "$BASE/posts/$POST_ID/schedule" -d "$SCHEDULE_BODY"
Der Zeitpunkt muss in der Zukunft liegen und innerhalb des 90-Tage-Horizonts; der UTC-Zeitpunkt und
die Anzeigezeitzone werden getrennt gespeichert. Läuft dein API-Key zu oder vor diesem
Zeitpunkt ab, enthält die angenommene Antwort einen warnings-Eintrag mit dem Code
key_expires_before_schedule. Die Zustellung bleibt geplant, aber sie muss
geprüft und unter einem aktiven Principal erneut übermittelt werden, bevor sie veröffentlicht werden kann. Die
gleiche Warnung bleibt beim Replay der Anfrage erhalten. Brich ab, solange sicher nicht in Anspruch genommen:
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/cancel
# Already submitted? → 409 too_late_to_cancel with the real state.
Wiederhole nur ein bekanntes fehlgeschlagenes Ziel (unbekannte/erfolgreiche werden abgelehnt):
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Medien (direkte Uploads)
Medienbytes passieren nie diese API.
# 1. Reserve bytes → direct instructions (presigned PUT, or multipart for large files)
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/upload-intents -d '{
"filename": "poster.jpg", "declaredMime": "image/jpeg", "declaredBytes": 1048576 }'
# 2. Upload bytes DIRECTLY to the returned URL with the documented method.
# 3. Finalize: the server verifies size/signature on the immutable final copy.
# Send ONLY the session identity (plus part receipts for multipart uploads)
#: bytes, MIME and checksum are observed server-side, never declared here.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
"sessionId": "…" }'
# multipart: include the ETag receipt of every uploaded part.
# Files at or above 50 MiB use multipart; use the returned part size and URLs.
# Upload every part and retain its ETag. Small files finalize with sessionId only.
# These are alternative finalization shapes, not two consecutive operations.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
"sessionId": "…",
"multipart": { "parts": [ { "partNumber": 1, "etag": "…" } ] } }'
# 4. Status/expiry only: there is no permanent public media URL
curl -s -H "$AUTH" $BASE/media/$ASSET_ID
Dateien sind temporär: geplante Beiträge behalten ihre Medien bis zur Veröffentlichung, und ein
dynamisches deleteAfter (oder null) wird immer angezeigt. Bewahre deine Originale auf.
Nutzung
GET /usage berichtet Plan, verbundene/reservierte Konto-Slots, Mitglieder, Storage,
den 90-Tage-Horizont und Rate-Informationen. Aktivitätszahlen sind nur Betriebskennzahlen:
ein Rest-Posting-Zähler existiert nirgendwo im Produkt.
Paginierung
Listen-Endpunkte verwenden opake Cursor: ?limit=25&cursor=<nextCursor>. Zeitstempel sind
UTC ISO-8601. Fahre fort, bis nextCursor null ist; eine gefilterte Beitragsseite kann
leer sein, während ihr nicht-nuller Cursor auf ältere, noch zu scannende Datensätze zeigt.
Bevorzuge Webhooks (siehe Webhooks) oder begrenztes Polling mit Backoff
statt engen Statusschleifen.
Limits und Teilerfolg
Ziel-Capabilities (aus GET /capabilities) tragen die strengsten
effektiven Limits: App, Provider, Netzwerk und Konto. Wenn ein Limit eine Anfrage blockiert,
ist der Fehler-Umschlag umsetzbar:
{
"error": {
"code": "storage_limit",
"message": "Active temporary media exceeds this plan's storage allowance.",
"retryable": false,
"requestId": "…"
}
}
account_limit, seat_limit, storage_limit, subscription_inactive und
trial_expired sind 402-Antworten; nichts wird gelöscht, und Entwürfe/eingereihte Arbeit bleibt
für die Zeit nach einem Upgrade erhalten.
Ein Publish/Schedule ist ein Batch unabhängiger Ziel-Jobs. Teilerfolg ist normal und wird pro Ziel berichtet: nie als atomares Versprechen:
{
"post": {
"postId": "…",
"version": 4,
"status": "partially_published",
"deliveries": [
{ "id": "…", "accountId": "…", "network": "instagram", "state": "published",
"nativePostUrl": "https://instagram.com/p/…", "unresolvedExternalOutcome": false },
{ "id": "…", "accountId": "…", "network": "linkedin", "state": "reconnect_required",
"nativePostUrl": null, "lastErrorCode": "reconnect_required" }
]
},
"requestId": "…"
}
Wiederhole nur das fehlgeschlagene Ziel (POST /deliveries/{id}/retry); erfolgreiche
Ziele werden nie erneut gesendet. Zustimmungs-/Verbindungsanforderungen geben
requires_action mit sicheren Anweisungen zurück, nie ein Secret.
Vollständige Referenz
Für TikTok gibt GET /accounts/{id}/tiktok/settings die aktuellen
Datenschutz-Auswahlen, Interaktionsberechtigungen, das Dauer-Limit und die Verfügbarkeit des Veröffentlichungsmodus
des verbundenen Creators zurück. Er erfordert accounts:read und beachtet die Key-Zulassungsliste.
Das Speichern eines Entwurfs oder das Lesen dieser Einstellungen stellt keine Zustimmung bereit.
Ein Publish/Schedule ohne aktuelle menschliche Bestätigung gibt HTTP 409
consent_required mit error.requiresAction.url zurück, das auf den gespeicherten Entwurf
im authentifizierten Composer zeigt. Die Validierung kann dieselbe Übergabe neben
ihren strukturierten Problemen zurückgeben. Die Person prüft dort das exakte Video und den Beitragstext und trifft
ausdrückliche Auswahlen; Produktkeys und MCP können nicht in ihrem Namen bestätigen.
Nachdem eine Person bestätigt hat, wiederhole über den normalen gemeinsamen Veröffentlichungsdienst.
Das Bearbeiten des Inhalts oder das Ändern der Zielidentität erfordert eine erneute Prüfung.
Die Übergabe-URL enthält keinen Produktkey, Token oder signierte Medien-URL und gewährt einer
Person ohne Arbeitsbereichs-Mitgliedschaft keinen Zugriff. Ihre Arbeitsbereichs-UUID identifiziert
den Arbeitsbereich des Keys; ein Browser mit einem anderen ausgewählten Arbeitsbereich muss nach einer aktuellen Mitgliedschaftsprüfung
explizit wechseln, bevor er diesen Entwurf prüft.
Siehe die OpenAPI-Spezifikation für den vollständigen, aktuellen Vertrag. UI, REST und MCP lesen alle dieselben Dienste, daher wenden sie dieselben Arbeitsbereichsregeln an. Ergebnisse spiegeln den aktuellen Zustand jeder Anfrage wider; getrennte Anfragen können zwischengelagerte Aktualisierungen beobachten.