Revisionato 2026-11-11 · Versione API 2026-11-09 · Leggi Markdown
Guida rapida all'API AiVideoEditor
Base URL: https://<your-app-host>/api/v1 (sviluppo locale: http://localhost:3006/api/v1).
Autenticazione
Crea una product key in Developers nella navigazione del workspace (/app/developers). La chiave in chiaro
(pk_v1_…) viene mostrata esattamente una volta; vengono memorizzati solo un hash e un breve prefisso.
Inviala come bearer token:
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
Le chiavi portano scope espliciti (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) e una allowlist opzionale
di account. Una chiave solo bozze omette posts:publish e quindi non può
pubblicare, programmare, annullare o riprovare. Le chiavi non possono mai creare altre chiavi o modificare
la fatturazione. La revoca di una chiave mette in pausa i suoi job non inviati come requires_action: nulla viene
eliminato, e la UI di revoca mostra prima il conteggio dei job in sospeso coinvolti.
Regole fondamentali
- Ogni mutazione richiede un header
Idempotency-Key. Stessa chiave + stesso corpo → lo stesso risultato registrato (stessi ID di consegna). Stessa chiave + corpo diverso →409 idempotency_conflict. - Le modifiche e la programmazione richiedono
expectedVersion; una versione non aggiornata restituisce409 revision_conflictcon la versione corrente inerror.details.currentVersion. 202da publish/schedule significa accettato per l'invio, mai "pubblicato". Segui gli esiti conGET /posts/{id}, webhook del cliente o polling limitato.- I limiti di frequenza sono limiti tecnici di velocità per workspace (60/120/240 req/min in
base al piano;
429+Retry-After). Non esiste quota di richieste o di pubblicazione: la pubblicazione è illimitata su ogni piano a pagamento. - Gli errori usano la busta normalizzata:
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
End-to-end: bozza → valida → pubblica → osserva
L'esempio richiede Bash, curl, jq, Node 22+, un workspace attivo,
una Facebook Page o una destinazione LinkedIn collegata, e una chiave con
accounts:read, posts:read, posts:write e posts:publish. Imposta
ACCOUNT_ID su una destinazione consentita da /accounts; verifica il suo supporto
al formato testo in /capabilities. Eseguire il comando di pubblicazione pubblica contenuto reale.
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"
Per le destinazioni immagine/video, carica e finalizza i media prima,
poi usa gli ID degli asset restituiti in mediaIds e un formato di destinazione idoneo.
Osserva i singoli ID di consegna dalla risposta accettata; usa webhook o un
polling di stato limitato con backoff. Una singola lettura immediata dello stato può risultare ancora in sospeso.
Programmare invece di pubblicare
Usa questo passo su una bozza invece di il passaggio di pubblicazione qui sopra. Recupera di nuovo la sua versione corrente dopo qualsiasi modifica. Questo calcola un istante futuro invece di usare una data di esempio destinata a scadere.
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'istante deve essere futuro e entro l'orizzonte di 90 giorni; l'istante UTC e
il fuso orario di visualizzazione sono memorizzati separatamente. Se la tua chiave API scade a quell'istante o prima,
la risposta accettata include una voce warnings con codice
key_expires_before_schedule. La consegna resta programmata, ma deve essere
rivista e inviata di nuovo sotto un principal attivo prima di poter pubblicare. Lo
stesso avviso viene conservato quando si ripete la richiesta. Annulla finché il lavoro resta sicuramente non preso in carico:
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.
Riprova solo una destinazione nota fallita (esiti sconosciuti/riusciti vengono rifiutati):
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Media (upload diretti)
I byte dei media non passano mai attraverso questa 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
I file sono temporanei: i post programmati conservano i loro media attraverso la pubblicazione, e un
deleteAfter dinamico (o null) viene sempre mostrato. Conserva i tuoi originali.
Utilizzo
GET /usage riporta piano, slot account collegati/riservati, membri, storage,
l'orizzonte di 90 giorni e informazioni sui limiti di frequenza. I numeri di attività sono solo metriche operative:
non esiste alcun contatore di post rimanenti da nessuna parte nel prodotto.
Paginazione
Gli endpoint di lista usano cursori opachi: ?limit=25&cursor=<nextCursor>. I timestamp sono
UTC ISO-8601. Continua finché nextCursor è null; una pagina di post filtrata può
essere vuota mentre il suo cursore non nullo punta a record più vecchi ancora da scansionare.
Preferisci webhook (vedi webhook) o polling limitato con backoff
a stretti cicli di stato.
Limiti e successo parziale
Le capability delle destinazioni (da GET /capabilities) portano i limiti effettivi più
rigidi: app, provider, rete e account. Quando un limite blocca una
richiesta, la busta di errore è azionabile:
{
"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 e
trial_expired sono risposte 402; nulla viene eliminato, e le bozze e il lavoro in coda vengono
conservati per dopo l'upgrade.
Una pubblicazione/programmazione è un batch di job di destinazione indipendenti. Il successo parziale è normale e viene riportato per destinazione: mai come una promessa atomica:
{
"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": "…"
}
Riprova solo la destinazione fallita (POST /deliveries/{id}/retry); le destinazioni
riuscite non vengono mai inviate di nuovo. I requisiti di consenso/riconnessione restituiscono
requires_action con istruzioni sicure, mai un segreto.
Riferimento completo
Per TikTok, GET /accounts/{id}/tiktok/settings restituisce le scelte di privacy correnti del creator
collegato, i permessi di interazione, il limite di durata e la disponibilità della
modalità di pubblicazione. Richiede accounts:read e rispetta la allowlist della chiave.
Salvare una bozza o leggere queste impostazioni non fornisce il consenso.
Una pubblicazione/programmazione priva dell'attuale conferma umana restituisce HTTP 409
consent_required con error.requiresAction.url che punta alla bozza salvata
nel composer autenticato. La validazione può restituire lo stesso handoff insieme
ai suoi problemi strutturati. La persona esamina lì l'esatto video/testo del post e fa
scelte esplicite; le product key e MCP non possono confermare al suo posto.
Dopo che una persona conferma, riprova attraverso il normale servizio di pubblicazione condiviso.
Modificare il contenuto o cambiare l'identità della destinazione richiede una nuova revisione.
L'URL di handoff non contiene product key, token o URL dei media firmati e non concede
accesso a una persona che non ha membership del workspace. Il suo UUID del workspace identifica
il workspace della chiave; un browser con un workspace selezionato diverso deve passare esplicitamente
all'altro dopo un controllo di membership corrente prima di esaminare questa bozza.
Vedi la specifica OpenAPI per il contratto completo e aggiornato. UI, REST e MCP leggono tutti gli stessi servizi, quindi applicano le stesse regole del workspace. I risultati riflettono lo stato corrente di ogni richiesta; richieste separate possono osservare aggiornamenti intermedi.