AiVideoEditor
Ücretsiz başlayın
Menü

İnceleme 2026-11-11 · API sürümü 2026-11-09 · Markdown oku

AiVideoEditor API hızlı başlangıç

Temel URL: https://<your-app-host>/api/v1 (yerel geliştirme: http://localhost:3006/api/v1).

Kimlik doğrulama

Çalışma alanı gezinmesindeki Developers bölümünde (/app/developers) bir ürün anahtarı oluşturun. Düz metin anahtar (pk_v1_…) tam bir kez gösterilir; yalnızca bir karma ve kısa bir önek saklanır. Bunu bearer token olarak gönderin:

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

Anahtarlar açık yetki kapsamları (accounts:read, media:write, posts:read, posts:write, posts:publish, usage:read, webhooks:manage) ve isteğe bağlı bir hesap izin listesi taşır. Yalnızca taslak amaçlı bir anahtar posts:publish kapsamını içermez ve bu nedenle yayınlayamaz, zamanlayamaz, iptal edemez veya yeniden deneyemez. Anahtarlar asla başka anahtarlar oluşturamaz veya faturalamayı değiştiremez. Bir anahtarı iptal etmek, gönderilmemiş işlerini requires_action olarak duraklatır: hiçbir şey silinmez ve iptal arayüzü önce etkilenen bekleyen iş sayısını gösterir.

Temel kurallar

  • Her mutasyon bir Idempotency-Key başlığı gerektirir. Aynı anahtar + aynı gövde → aynı kaydedilen sonuç (aynı teslim kimlikleri). Aynı anahtar + farklı gövde → 409 idempotency_conflict.
  • Düzenlemeler ve zamanlama expectedVersion gerektirir; bayat bir sürüm, geçerli sürümü error.details.currentVersion içinde vererek 409 revision_conflict döndürür.
  • Yayınla/zamanla'dan gelen 202, gönderime kabul edildi anlamına gelir, asla "yayımlandı" değil. Sonuçları GET /posts/{id}, müşteri webhook'ları veya sınırlı yoklamayla izleyin.
  • Hız sınırları çalışma alanı başına teknik hız sınırlarıdır (plana göre 60/120/240 istek/dk; 429 + Retry-After). İstek veya paylaşım kotası yoktur: her ücretli planda paylaşım sınırsızdır.
  • Hatalar normalleştirilmiş zarfı kullanır: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.

Uçtan uca: taslak → doğrula → yayınla → gözlemle

Örnek; Bash, curl, jq, Node 22+, etkin bir çalışma alanı, bağlı bir Facebook Sayfası veya LinkedIn hedefi ve accounts:read, posts:read, posts:write ve posts:publish kapsamlarına sahip bir anahtar gerektirir. ACCOUNT_ID değerini /accounts yanıtlarından izin verilen bir hedefe ayarlayın; /capabilities içinden metin biçimi desteğini kontrol edin. Yayınlama komutunu çalıştırmak gerçek içerik paylaşır.

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"

Görsel/video hedefleri için önce medyayı yükleyin ve sonlandırın; ardından döndürülen varlık kimliklerini mediaIds içinde ve uygun bir hedef biçimiyle kullanın. Kabul yanıtından tek tek teslim kimliklerini gözlemleyin; webhook'ları veya geri çekilmeli sınırlı bir durum yoklaması kullanın. Tek bir anlık durum okuması hâlâ beklemede olabilir.

Yayınlamak yerine zamanlama

Bunu yukarıdaki yayın adımı yerine bir taslakta kullanın. Herhangi bir düzenlemeden sonra geçerli sürümünü yeniden alın. Bu, süresi dolacak örnek bir tarih kullanmak yerine gelecekteki bir an hesaplar.

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"

An, gelecekte ve 90 günlük ufuk içinde olmalıdır; UTC anı ve görüntüleme saat dilimi ayrı saklanır. API anahtarınız o anda veya öncesinde sona erecekse, kabul yanıtı key_expires_before_schedule koduyla bir warnings girdisi içerir. Teslimat zamanlanmış olarak kalır, ancak yayınlanabilmesi için etkin bir prensip altında gözden geçirilip yeniden gönderilmelidir. Aynı uyarı, istek yeniden oynatıldığında korunur. Güvenle talep edilmediği sürece iptal edin:

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.

Yalnızca bilinen başarısız bir hedef için yeniden deneyin (bilinmeyen/başarılı olanlar reddedilir):

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

Medya (doğrudan yüklemeler)

Medya baytları bu API'den asla geçmez.

# 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

Dosyalar geçicidir: zamanlanmış paylaşımlar medyalarını yayınlamaya kadar korur ve dinamik bir deleteAfter (veya null) her zaman gösterilir. Orijinallerinizi saklayın.

Kullanım

GET /usage; planı, bağlı/ayrılmış hesap slotlarını, üyeleri, depolamayı, 90 günlük ufkunu ve hız bilgisini raporlar. Etkinlik sayıları yalnızca operasyonel ölçütlerdir: üründe hiçbir yerde kalan paylaşım sayacı yoktur.

Sayfalama

Liste uç noktaları opak imleçler kullanır: ?limit=25&cursor=<nextCursor>. Zaman damgaları UTC ISO-8601 biçimindedir. nextCursor null olana kadar devam edin; filtrelenmiş bir gönderiler sayfası, boş olmayan imleci taranacak eski kayıtlara işaret ederken boş olabilir. Sıkı durum döngüleri yerine webhook'ları (webhooks bölümüne bakın) veya geri çekilmeli sınırlı yoklamayı tercih edin.

Sınırlar ve kısmi başarı

Hedef yetenekleri (GET /capabilities üzerinden) en katı etkin sınırları taşır: uygulama, sağlayıcı, ağ ve hesap. Bir sınır bir isteği engellediğinde hata zarfı eyleme dönüktür:

{
  "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 ve trial_expired 402 yanıtlarıdır; hiçbir şey silinmez ve taslaklar/kuyruktaki işler yükseltme sonrası için korunur.

Yayın/zamanlama, bağımsız hedef işlerinden oluşan bir toplu işlemdir. Kısmi başarı normaldir ve hedef başına raporlanır; asla atomik bir vaat değildir:

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

Yalnızca başarısız hedefi yeniden deneyin (POST /deliveries/{id}/retry); başarılı hedefler asla yeniden gönderilmez. Onay/yeniden bağlantı gereksinimleri, gizli anahtar değil, güvenli talimatlarla requires_action döndürür.

Eksiksuz başvuru

TikTok için GET /accounts/{id}/tiktok/settings; bağlı creator'ın geçerli gizlilik seçimlerini, etkileşim izinlerini, süre sınırını ve yayınlama modu kullanılabilirliğini döndürür. accounts:read gerektirir ve anahtarın izin listesine uyar. Taslak kaydetmek veya bu ayarları okumak onay sağlamaz.

Güncel insan onayı olmayan bir yayın/zamanlama, kaydedilen taslağa işaret eden error.requiresAction.url ile HTTP 409 consent_required döndürür. Doğrulama, yapılandırılmış sorunlarının yanı sıra aynı devri de döndürebilir. Kişi tam video/paylaşım metnini orada inceler ve gerekli seçimleri açıkça yapar; ürün anahtarları ve MCP adına onay veremez. Kişi onayladıktan sonra, normal paylaşılan yayınlama servisi üzerinden yeniden deneyin. İçeriği düzenlemek veya hedef kimliğini değiştirmek yeniden inceleme gerektirir. Devir URL'si ürün anahtarı, token veya imzalı medya URL'si içermez ve çalışma alanı üyeliği olmayan bir kişiye erişim vermez. Çalışma alanı UUID'si anahtarın çalışma alanını tanımlar; farklı bir çalışma alanı seçilmiş bir tarayıcı, bu taslağı incelemeden önce geçerli üyelik kontrolünden sonra açıkça geçiş yapmalıdır.

Eksiksiz ve güncel sözleşme için OpenAPI belirtimine bakın. UI, REST ve MCP aynı servisleri okur; bu nedenle aynı çalışma alanı kurallarını uygularlar. Sonuçlar her isteğin geçerli durumunu yansıtır; ayrı istekler aradaki güncellemeleri görebilir.