İ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-Keybaş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
expectedVersiongerektirir; bayat bir sürüm, geçerli sürümüerror.details.currentVersioniçinde vererek409 revision_conflictdö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.