Revisado em 2026-11-11 · Versão da API 2026-11-09 · Ler Markdown
Início rápido da API do AiVideoEditor
URL base: https://<your-app-host>/api/v1 (desenvolvimento local: http://localhost:3006/api/v1).
Autenticação
Crie uma chave de produto em Developers na navegação do espaço de trabalho (/app/developers). A chave em texto puro
(pk_v1_…) é exibida exatamente uma vez; apenas um hash e um prefixo curto são armazenados.
Envie-a como token bearer:
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
As chaves carregam escopos explícitos (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) e uma allowlist
opcional de contas. Uma chave somente para rascunhos omite posts:publish e, portanto, não pode
publicar, agendar, cancelar nem repetir. As chaves nunca podem criar outras chaves nem
alterar cobranças. Revogar uma chave pausa seus trabalhos não enviados como requires_action: nada é
excluído, e a interface de revogação mostra primeiro a contagem de trabalhos pendentes afetados.
Regras fundamentais
- Toda mutação exige um cabeçalho
Idempotency-Key. Mesma chave + mesmo corpo → o mesmo resultado registrado (mesmos IDs de entrega). Mesma chave + corpo diferente →409 idempotency_conflict. - Edições e agendamentos exigem
expectedVersion; uma versão desatualizada retorna409 revision_conflictcom a versão atual emerror.details.currentVersion. 202de publish/schedule significa aceito para despacho, nunca "publicado". Acompanhe os resultados comGET /posts/{id}, webhooks do cliente ou sondagem limitada.- Os limites de taxa são limites técnicos de velocidade por espaço de trabalho (60/120/240 req/min por
plano;
429+Retry-After). Não há cota de requisições nem de publicações: publicar é ilimitado em todos os planos pagos. - Os erros usam o envelope normalizado:
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
Ponta a ponta: rascunho → validar → publicar → observar
O exemplo requer Bash, curl, jq, Node 22+, um espaço de trabalho ativo,
uma Página do Facebook ou um destino LinkedIn conectado e uma chave com
accounts:read, posts:read, posts:write e posts:publish. Defina
ACCOUNT_ID como um destino permitido a partir de /accounts; verifique o suporte ao formato
de texto dele em /capabilities. Executar o comando de publicação publica conteúdo real.
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"
Para destinos de imagem/vídeo, primeiro envie e finalize a mídia,
depois use os IDs de ativo retornados em mediaIds e um formato de destino elegível.
Observe os IDs de entrega individuais na resposta aceita; use webhooks ou uma
sondagem de status limitada com backoff. Uma única leitura imediata de status ainda pode estar pendente.
Agendar em vez de publicar
Use isto em um rascunho em vez da etapa de publicação acima. Obtenha novamente a versão atual dele após qualquer edição. Isto calcula um instante futuro em vez de usar uma data de exemplo que expirará.
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"
O instante deve estar no futuro e dentro do horizonte de 90 dias; o instante UTC e o
fuso horário de exibição são armazenados separadamente. Se sua chave de API expirar naquele instante
ou antes dele, a resposta aceita inclui uma entrada warnings com o código
key_expires_before_schedule. A entrega permanece agendada, mas deve ser
revisada e reenviada sob um titular ativo antes de poder ser publicada. O
mesmo aviso é preservado ao repetir a solicitação. Cancele enquanto estiver seguramente não reivindicado:
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.
Tente novamente apenas um destino com falha conhecida (desconhecido/bem-sucedido são recusados):
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Mídia (uploads diretos)
Os bytes de mídia nunca passam por esta 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
Os arquivos são temporários: publicações agendadas mantêm sua mídia durante a publicação, e um
deleteAfter dinâmico (ou nulo) é sempre exibido. Guarde seus originais.
Uso
GET /usage informa o plano, os slots de contas conectadas/reservadas, os membros, o armazenamento,
o horizonte de 90 dias e as informações de taxa. Os números de atividade são apenas métricas operacionais:
não há nenhum contador de publicações restantes em lugar nenhum do produto.
Paginação
Os endpoints de lista usam cursores opacos: ?limit=25&cursor=<nextCursor>. Os carimbos de data/hora estão em
UTC ISO-8601. Continue até que nextCursor seja null; uma página de publicações filtrada pode
estar vazia enquanto seu cursor não nulo aponta para registros mais antigos ainda a serem varridos.
Prefira webhooks (veja webhooks) ou sondagem limitada com backoff
a loops apertados de status.
Limites e sucesso parcial
As capacidades de destino (de GET /capabilities) carregam os limites
efetivos mais rigorosos: aplicativo, provedor, rede e conta. Quando um limite bloqueia uma
solicitação, o envelope de erro é acionável:
{
"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 são respostas 402; nada é excluído, e rascunhos/trabalhos em fila são
preservados para depois de uma atualização de plano.
Uma publicação/agendamento é um lote de trabalhos de destino independentes. O sucesso parcial é normal e relatado por destino: nunca como uma promessa atômica:
{
"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": "…"
}
Tente novamente apenas o destino com falha (POST /deliveries/{id}/retry); destinos
bem-sucedidos nunca são reenviados. Requisitos de consentimento/reconexão retornam
requires_action com instruções seguras, nunca um segredo.
Referência completa
Para o TikTok, GET /accounts/{id}/tiktok/settings retorna as escolhas de privacidade atuais,
as permissões de interação, o limite de duração e a disponibilidade de modo de publicação
do criador conectado. Requer accounts:read e honra a allowlist da chave.
Salvar um rascunho ou ler essas configurações não fornece consentimento.
Uma publicação/agendamento sem confirmação humana atual retorna HTTP 409
consent_required com error.requiresAction.url apontando para o rascunho salvo
no compositor autenticado. A validação pode retornar a mesma transferência junto com
seus problemas estruturados. A pessoa revisa o vídeo/legenda exatos e faz
escolhas explícitas ali; chaves de produto e MCP não podem confirmar em seu nome.
Depois que uma pessoa confirma, repita por meio do serviço de publicação compartilhado normal.
Editar o conteúdo ou alterar a identidade do destino exige nova revisão.
A URL de transferência não contém chave de produto, token nem URL de mídia assinada e não concede
acesso a uma pessoa que não tenha membership no espaço de trabalho. O UUID de espaço de trabalho dela identifica
o espaço de trabalho da chave; um navegador com um espaço de trabalho selecionado diferente deve trocar
explicitamente após uma verificação atual de membership antes de revisar este rascunho.
Consulte a especificação OpenAPI para obter o contrato completo e atual. A UI, a REST e o MCP leem os mesmos serviços, por isso aplicam as mesmas regras do espaço de trabalho. Os resultados refletem o estado atual de cada solicitação; solicitações separadas podem observar atualizações intermediárias.