Revisada el 2026-11-11 · Versión de API 2026-11-09 · Leer Markdown
Inicio rápido de la API de AiVideoEditor
URL base: https://<tu-host-de-app>/api/v1 (desarrollo local: http://localhost:3006/api/v1).
Autenticación
Crea una clave de producto en Developers en la navegación del espacio de trabajo (/app/developers). La clave en texto plano
(pk_v1_…) se muestra exactamente una vez; solo se almacenan un hash y un prefijo corto.
Envíala como token bearer:
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
Las claves llevan scopes explícitos (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) y una lista de cuentas
permitidas opcional. Una clave solo de borradores omite posts:publish y por tanto no puede
publicar, programar, cancelar ni reintentar. Las claves nunca pueden crear otras claves ni cambiar
la facturación. Revocar una clave pausa sus trabajos no enviados como requires_action: no se
elimina nada, y la interfaz de revocación muestra primero el número de trabajos pendientes afectados.
Reglas básicas
- Toda mutación requiere una cabecera
Idempotency-Key. Misma clave + mismo cuerpo → el mismo resultado registrado (mismos IDs de entrega). Misma clave + cuerpo distinto →409 idempotency_conflict. - Las ediciones y la programación requieren
expectedVersion; una versión obsoleta devuelve409 revision_conflictcon la versión actual enerror.details.currentVersion. - Un
202de publish/schedule significa aceptado para despacho, nunca "publicado". Sigue los resultados conGET /posts/{id}, webhooks de cliente o sondeos acotados. - Los límites de tasa son límites de velocidad técnicos por espacio de trabajo (60/120/240 req/min según
el plan;
429+Retry-After). No hay cuota de solicitudes ni de publicaciones: publicar es ilimitado en todos los planes de pago. - Los errores usan el sobre normalizado:
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
De extremo a extremo: borrador → validar → publicar → observar
El ejemplo requiere Bash, curl, jq, Node 22+, un espacio de trabajo activo,
una Página de Facebook o un destino LinkedIn conectados, y una clave con
accounts:read, posts:read, posts:write y posts:publish. Establece
ACCOUNT_ID con un destino permitido de /accounts; comprueba su compatibilidad con formato
de texto en /capabilities. Ejecutar el comando de publicación publica contenido 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 imagen/vídeo, sube y finaliza los medios primero,
y luego usa los IDs de recurso devueltos en mediaIds con un formato de destino elegible.
Observa los IDs de entrega individuales de la respuesta aceptada; usa webhooks o un
sondeo de estado acotado con backoff. Una única lectura de estado inmediata puede seguir pendiente.
Programar en lugar de publicar
Usa esto en un borrador en lugar de el paso de publicación anterior. Vuelve a obtener su versión actual después de cualquier edición. Esto calcula un instante futuro en lugar de usar una fecha de ejemplo que caducará.
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"
El instante debe ser futuro y estar dentro del horizonte de 90 días; el instante UTC y la
zona horaria de visualización se almacenan por separado. Si tu clave de API caduca en ese instante o antes,
la respuesta aceptada incluye una entrada warnings con el código
key_expires_before_schedule. La entrega sigue programada, pero debe ser
revisada y reenviada bajo un principal activo antes de poder publicarse. La misma
advertencia se conserva al reproducir la solicitud. Cancela mientras esté seguramente sin reclamar:
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.
Reintenta solo un destino con fallo conocido (los desconocidos/exitosos se rechazan):
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Medios (subidas directas)
Los bytes de los medios nunca pasan 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
Los archivos son temporales: las publicaciones programadas conservan sus medios durante la publicación, y un
deleteAfter dinámico (o null) se muestra siempre. Conserva tus originales.
Uso
GET /usage informa del plan, de los slots de cuentas conectadas/reservadas, de los miembros, del almacenamiento,
del horizonte de 90 días y de la información de tasa. Los números de actividad son solo métricas operativas:
no hay ningún contador de publicaciones restantes en ningún lugar del producto.
Paginación
Los endpoints de lista usan cursores opacos: ?limit=25&cursor=<nextCursor>. Las marcas de tiempo son
UTC ISO-8601. Continúa hasta que nextCursor sea null; una página de publicaciones filtrada puede
estar vacía mientras su cursor no nulo apunta a registros más antiguos aún por escanear.
Prefiere los webhooks (ver webhooks) o un sondeo acotado con backoff
antes que bucles de estado ajustados.
Límites y éxito parcial
Las capacidades de destino (de GET /capabilities) llevan los límites efectivos más estrictos:
aplicación, proveedor, red y cuenta. Cuando un límite bloquea una
solicitud, el sobre de error es accionable:
{
"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 y
trial_expired son respuestas 402; no se elimina nada, y los borradores/trabajos en cola se
conservan para después de una mejora del plan.
Una publicación/programación es un lote de trabajos de destino independientes. El éxito parcial es normal y se informa por destino: nunca como una promesa 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": "…"
}
Reintenta solo el destino fallido (POST /deliveries/{id}/retry); los destinos
exitosos nunca se reenvían. Los requisitos de consentimiento/reconexión devuelven
requires_action con instrucciones seguras, nunca un secreto.
Referencia completa
Para TikTok, GET /accounts/{id}/tiktok/settings devuelve las elecciones de privacidad actuales del creador conectado,
los permisos de interacción, el límite de duración y la disponibilidad del modo de publicación.
Requiere accounts:read y respeta la lista de cuentas permitidas de la clave.
Guardar un borrador o leer estas configuraciones no suministra el consentimiento.
Una publicación/programación sin la confirmación humana vigente devuelve HTTP 409
consent_required con error.requiresAction.url apuntando al borrador guardado
en el compositor autenticado. La validación puede devolver el mismo traspaso junto con
sus problemas estructurados. La persona revisa el vídeo/subtítulo exacto y toma
allí las elecciones explícitas; las claves de producto y MCP no pueden confirmar en su nombre.
Después de que una persona confirme, reintenta a través del servicio de publicación compartido normal.
Editar el contenido o cambiar la identidad del destino requiere una revisión nueva.
La URL de traspaso no contiene clave de producto, token ni URL de medios firmada y no concede
acceso a una persona que carezca de membresía en el espacio de trabajo. Su UUID de espacio de trabajo identifica
el espacio de trabajo de la clave; un navegador con un espacio de trabajo seleccionado diferente debe cambiar
explícitamente tras una comprobación de membresía vigente antes de revisar este borrador.
Consulta la especificación OpenAPI para el contrato completo y actual. La UI, REST y MCP leen los mismos servicios, por lo que aplican las mismas reglas del espacio de trabajo. Los resultados reflejan el estado actual de cada solicitud; solicitudes separadas pueden observar actualizaciones intermedias.