AiVideoEditor
Inizia gratis
Menù

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 restituisce 409 revision_conflict con la versione corrente in error.details.currentVersion.
  • 202 da publish/schedule significa accettato per l'invio, mai "pubblicato". Segui gli esiti con GET /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.