Vérifié le 2026-11-11 · Version API 2026-11-09 · Lire le Markdown
Démarrage rapide de l'API AiVideoEditor
URL de base : https://<your-app-host>/api/v1 (dev local : http://localhost:3006/api/v1).
Authentification
Créez une clé de produit dans Developers dans la navigation de l'espace de travail (/app/developers). La clé en clair
(pk_v1_…) est affichée une seule fois ; seuls un hash et un préfixe court sont stockés.
Envoyez-la comme jeton bearer :
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
Les clés portent des scopes explicites (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) et une liste d'autorisation
de comptes optionnelle. Une clé limitée aux brouillons omet posts:publish et ne peut donc pas
publier, planifier, annuler ni retenter. Les clés ne peuvent jamais créer d'autres clés ni modifier
la facturation. Révoquer une clé met en pause ses tâches non envoyées en tant que requires_action :
rien n'est supprimé, et l'UI de révocation affiche d'abord le nombre de tâches en attente affectées.
Règles fondamentales
- Chaque mutation requiert un en-tête
Idempotency-Key. Même clé + même corps → le même résultat enregistré (mêmes IDs de livraison). Même clé + corps différent →409 idempotency_conflict. - Les modifications et la planification requièrent
expectedVersion; une version obsolète renvoie409 revision_conflictavec la version actuelle danserror.details.currentVersion. - Un
202de publish/schedule signifie accepté pour envoi, jamais « publié ». Suivez les résultats avecGET /posts/{id}, les webhooks client ou un polling borné. - Les limites de débit sont des limites techniques de vitesse par espace de travail (60/120/240 req/min selon le
plan ;
429+Retry-After). Il n'existe aucun quota de requêtes ni de publication : la publication est illimitée sur chaque plan payant. - Les erreurs utilisent l'enveloppe normalisée :
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
De bout en bout : brouillon → validation → publication → observation
L'exemple requiert Bash, curl, jq, Node 22+, un espace de travail actif,
une Page Facebook connectée ou une destination LinkedIn, et une clé avec
accounts:read, posts:read, posts:write et posts:publish. Définissez
ACCOUNT_ID sur une destination autorisée depuis /accounts ; vérifiez la prise en charge
de son format texte dans /capabilities. L'exécution de la commande publish publie du contenu réel.
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"
Pour les destinations image/vidéo, téléversez et finalisez d'abord les médias,
puis utilisez les IDs d'asset retournés dans mediaIds et un format de destination éligible.
Observez les IDs de livraison individuels depuis la réponse acceptée ; utilisez des webhooks ou un
sondage de statut borné avec backoff. Une seule lecture immédiate du statut peut encore être en attente.
Planifier au lieu de publier
Utilisez ceci sur un brouillon au lieu de l'étape de publication ci-dessus. Récupérez à nouveau sa version actuelle après toute modification. Ceci calcule un instant futur plutôt que d'utiliser une date d'exemple qui expirera.
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"
L'instant doit être futur et dans l'horizon de 90 jours ; l'instant UTC et
le fuseau horaire d'affichage sont stockés séparément. Si votre clé d'API expire à cet instant ou avant,
la réponse acceptée inclut une entrée warnings avec le code
key_expires_before_schedule. La livraison reste planifiée, mais elle doit être
revue et resoumise sous un principal actif avant de pouvoir être publiée. Le
même avertissement est conservé lors du rejeu de la requête. Annulez tant que la livraison reste en sécurité sans être revendiquée :
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.
Retentez uniquement une destination en échec connue (les inconnues/réussies sont refusées) :
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Médias (téléversement direct)
Les octets des médias ne transitent jamais par cette 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
Les fichiers sont temporaires : les publications planifiées conservent leurs médias jusqu'à la publication, et un
deleteAfter dynamique (ou null) est toujours affiché. Gardez vos originaux.
Utilisation
GET /usage indique le plan, les emplacements de comptes connectés/réservés, les membres, le stockage,
l'horizon de 90 jours et les informations de débit. Les chiffres d'activité ne sont que des métriques
opérationnelles : il n'existe aucun compteur de publications restantes nulle part dans le produit.
Pagination
Les points de terminaison de liste utilisent des curseurs opaques : ?limit=25&cursor=<nextCursor>. Les horodatages sont
en UTC ISO-8601. Continuez jusqu'à ce que nextCursor soit null ; une page de publications filtrée peut
être vide alors que son curseur non null pointe vers des enregistrements plus anciens encore à parcourir.
Préférez les webhooks (voir webhooks) ou un polling borné avec backoff
aux boucles de statut serrées.
Limites et succès partiel
Les capacités des destinations (issues de GET /capabilities) portent les limites
effectives les plus strictes : application, fournisseur, réseau et compte. Quand une limite bloque une
requête, l'enveloppe d'erreur est exploitable :
{
"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 et
trial_expired sont des réponses 402 ; rien n'est supprimé, et les brouillons/travaux en file sont
conservés pour après une mise à niveau.
Une publication/planification est un lot de tâches de destination indépendantes. Le succès partiel est normal et signalé par destination : jamais comme une promesse atomique :
{
"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": "…"
}
Retentez uniquement la destination en échec (POST /deliveries/{id}/retry) ; les destinations
réussies ne sont jamais renvoyées. Les exigences de consentement/reconnexion renvoient
requires_action avec des instructions sûres, jamais un secret.
Référence complète
Pour TikTok, GET /accounts/{id}/tiktok/settings renvoie les choix de confidentialité actuels du
créateur connecté, les permissions d'interaction, la limite de durée et la disponibilité des
modes de publication. Cela requiert accounts:read et respecte la liste d'autorisation de la clé.
Enregistrer un brouillon ou lire ces réglages ne fournit pas le consentement.
Une publication/planification sans confirmation humaine actuelle renvoie HTTP 409
consent_required avec error.requiresAction.url pointant vers le brouillon enregistré
dans le composer authentifié. La validation peut renvoyer le même handoff en plus
de ses problèmes structurés. La personne examine la vidéo/légende exacte et y fait
des choix explicites ; les clés de produit et MCP ne peuvent pas confirmer en son nom.
Après la confirmation d'une personne, retentez via le service de publication partagé normal.
Modifier le contenu ou changer l'identité de la destination requiert une nouvelle revue.
L'URL de handoff ne contient ni clé de produit, ni jeton, ni URL de média signée et n'accorde
aucun accès à une personne qui n'est pas membre de l'espace de travail. Son UUID d'espace de travail identifie
l'espace de travail de la clé ; un navigateur avec un autre espace de travail sélectionné doit basculer
explicitement après une vérification d'appartenance actuelle avant d'examiner ce brouillon.
Voir la spécification OpenAPI pour le contrat complet et actuel. L'UI, REST et MCP lisent tous les mêmes services, donc ils appliquent les mêmes règles d'espace de travail. Les résultats reflètent l'état actuel de chaque requête ; des requêtes séparées peuvent observer des mises à jour intervenues entre-temps.