AiVideoEditor
Начните бесплатно
Меню

Проверено 2026-11-11 · версия API 2026-11-09 · Читать Markdown

Быстрый старт с API AiVideoEditor

Базовый URL: https://<your-app-host>/api/v1 (локальная разработка: http://localhost:3006/api/v1).

Аутентификация

Создайте ключ продукта в разделе Developers в навигации рабочего пространства (/app/developers). Открытый (plaintext) ключ (pk_v1_…) показывается ровно один раз; хранятся только хеш и короткий префикс. Отправляйте его как bearer-токен:

curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage

Ключи несут явные права (scopes) (accounts:read, media:write, posts:read, posts:write, posts:publish, usage:read, webhooks:manage) и необязательный список разрешенных аккаунтов. Ключ только для черновиков не имеет posts:publish и поэтому не может публиковать, планировать, отменять или повторять. Ключи никогда не могут создавать другие ключи или изменять биллинг. Отзыв ключа приостанавливает его неотправленные задания в статусе requires_action: ничего не удаляется, и интерфейс отзыва сначала показывает число затронутых ожидающих заданий.

Базовые правила

  • Каждая мутация требует заголовка Idempotency-Key. Тот же ключ + то же тело → тот же записанный результат (те же ID доставок). Тот же ключ + другое тело → 409 idempotency_conflict.
  • Правки и планирование требуют expectedVersion; устаревшая версия возвращает 409 revision_conflict с текущей версией в error.details.currentVersion.
  • 202 от publish/schedule означает принято к отправке, но никогда «опубликовано». Отслеживайте результаты через GET /posts/{id}, клиентские вебхуки или ограниченный опрос.
  • Лимиты запросов — это технические ограничения скорости на рабочее пространство (60/120/240 запросов/мин по тарифу; 429 + Retry-After). Квоты на запросы или публикации нет: публикация не ограничена на каждом платном тарифе.
  • Ошибки используют нормализованный конверт: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.

Сквозной пример: черновик → проверка → публикация → наблюдение

Для примера требуются Bash, curl, jq, Node 22+, активное рабочее пространство, подключенное назначение Facebook Page или LinkedIn и ключ с правами accounts:read, posts:read, posts:write и posts:publish. Установите ACCOUNT_ID в разрешенное назначение из /accounts; проверьте его поддержку текстового формата в /capabilities. Запуск команды публикации отправляет реальный контент.

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"

Для назначений с изображениями/видео сначала загрузите и финализируйте медиа, затем используйте возвращенные ID ресурсов в mediaIds и подходящий формат назначения. Наблюдайте за отдельными ID доставок из принятого ответа; используйте вебхуки или ограниченный опрос статуса с нарастающими задержками. Одно немедленное чтение статуса все еще может показывать ожидание.

Планирование вместо публикации

Используйте это для черновика вместо шага публикации выше. После любой правки снова получите его текущую версию. Здесь вычисляется будущий момент времени, а не используется пример даты, которая истечет.

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"

Момент времени должен быть в будущем и в пределах 90-дневного горизонта; UTC-момент и часовой пояс отображения хранятся отдельно. Если ваш ключ API истекает в этот момент или раньше, принятый ответ содержит запись warnings с кодом key_expires_before_schedule. Доставка остается запланированной, но ее нужно пересмотреть и повторно отправить под действующим субъектом, прежде чем она сможет быть опубликована. То же предупреждение сохраняется при повторном воспроизведении запроса. Отменяйте, пока задание безопасно не взято в работу:

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.

Повторяйте только известное неудавшееся назначение (неизвестные/успешные отклоняются):

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry

Медиа (прямые загрузки)

Байты медиа никогда не проходят через этот 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

Файлы временные: запланированные посты сохраняют свои медиа до публикации, и динамический deleteAfter (или null) всегда показывается. Храните свои оригиналы.

Использование

GET /usage сообщает тариф, подключенные/зарезервированные слоты аккаунтов, участников, хранилище, 90-дневный горизонт и информацию о лимитах запросов. Числа активности — только операционные метрики: счетчика оставшихся постов нет нигде в продукте.

Пагинация

Эндпоинты списков используют непрозрачные курсоры: ?limit=25&cursor=<nextCursor>. Метки времени — UTC ISO-8601. Продолжайте, пока nextCursor не станет null; отфильтрованная страница постов может быть пустой, пока ее ненулевой курсор указывает на еще не просмотренные более старые записи. Предпочитайте вебхуки (см. вебхуки) или ограниченный опрос с задержками вместо плотных циклов проверки статуса.

Лимиты и частичный успех

Возможности назначений (из GET /capabilities) дают самые строгие действующие лимиты: приложение, провайдер, сеть и аккаунт. Когда лимит блокирует запрос, конверт ошибки дает конкретные действия:

{
  "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 и trial_expired — это ответы 402; ничего не удаляется, а черновики и работы в очереди сохраняются до повышения тарифа.

Публикация/планирование — это набор независимых заданий назначений. Частичный успех нормален и сообщается по каждому назначению: никогда как атомарное обещание:

{
  "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": "…"
}

Повторяйте только неудавшееся назначение (POST /deliveries/{id}/retry); успешные назначения никогда не отправляются повторно. Требования согласия/переподключения возвращают requires_action с безопасными инструкциями, но никогда с секретом.

Полный справочник

Для TikTok GET /accounts/{id}/tiktok/settings возвращает текущие настройки приватности подключенного создателя, права на взаимодействия, лимит длительности и доступность режимов публикации. Требуется accounts:read, и учитывается список разрешенных аккаунтов ключа. Сохранение черновика или чтение этих настроек не дает согласия.

Публикация/планирование без текущего подтверждения человека возвращает HTTP 409 consent_required с error.requiresAction.url, указывающим на сохраненный черновик в аутентифицированном композере. Проверка может вернуть тот же хендофф вместе со своими структурированными проблемами. Человек просматривает точное видео и подпись к посту и явно делает там требуемые выборы; ключи продукта и MCP не могут подтвердить за него. После подтверждения человеком повторяйте через обычный общий сервис публикации. Изменение контента или смена идентичности назначения требует новой проверки. URL хендоффа не содержит ключа продукта, токена или подписанного URL медиа и не дает доступа человеку без участия в рабочем пространстве. Его UUID рабочего пространства идентифицирует рабочее пространство ключа; браузер с другим выбранным рабочим пространством должен явно переключиться после текущей проверки участия, прежде чем просматривать этот черновик.

См. спецификацию OpenAPI для полного, актуального контракта. UI, REST и MCP читают одни и те же сервисы, поэтому применяют одни и те же правила рабочего пространства. Результаты отражают текущее состояние каждого запроса; отдельные запросы могут наблюдать промежуточные обновления.