AiVideoEditor
Commencez gratuitement
Menu

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 renvoie 409 revision_conflict avec la version actuelle dans error.details.currentVersion.
  • Un 202 de publish/schedule signifie accepté pour envoi, jamais « publié ». Suivez les résultats avec GET /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.