AiVideoEditor
Kostenlos starten
Menü

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 liefert 409 revision_conflict mit der aktuellen Version in error.details.currentVersion.
  • 202 von publish/schedule bedeutet zur Zustellung angenommen, nie „veröffentlicht“. Verfolge Ergebnisse mit GET /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.