Ditinjau 2026-11-11 · Versi API 2026-11-09 · Baca Markdown
Panduan cepat API AiVideoEditor
URL dasar: https://<your-app-host>/api/v1 (pengembangan lokal: http://localhost:3006/api/v1).
Autentikasi
Buat kunci produk di Developers pada navigasi ruang kerja (/app/developers). Kunci
bentuk teks biasa (pk_v1_…) hanya ditampilkan tepat satu kali; hanya hash dan prefiks
pendek yang disimpan. Kirimkan sebagai bearer token:
curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage
Kunci membawa cakupan eksplisit (accounts:read, media:write, posts:read,
posts:write, posts:publish, usage:read, webhooks:manage) dan daftar
izin akun opsional. Kunci khusus draf tidak menyertakan posts:publish sehingga tidak dapat
menerbitkan, menjadwalkan, membatalkan, atau mencoba ulang. Kunci tidak akan pernah dapat
membuat kunci lain atau mengubah penagihan. Mencabut sebuah kunci menjeda pekerjaan
belum terkirimnya sebagai requires_action: tidak ada yang dihapus, dan UI pencabutan
menampilkan jumlah pekerjaan tertunda yang terdampak terlebih dahulu.
Aturan dasar
- Setiap mutasi memerlukan header
Idempotency-Key. Kunci sama + isi sama → hasil tercatat yang sama (ID pengiriman yang sama). Kunci sama + isi berbeda →409 idempotency_conflict. - Pengeditan dan penjadwalan memerlukan
expectedVersion; versi usang mengembalikan409 revision_conflictdengan versi terkini dierror.details.currentVersion. 202dari publish/schedule berarti diterima untuk pengiriman, bukan "diterbitkan". Lacak hasil denganGET /posts/{id}, webhook pelanggan, atau polling berbatas.- Batas laju adalah batas kecepatan teknis per ruang kerja (60/120/240 req/menit sesuai
paket;
429+Retry-After). Tidak ada kuota permintaan maupun posting: posting tidak terbatas pada setiap paket berbayar. - Kesalahan menggunakan amplop ternormalisasi:
{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.
Ujung ke ujung: draf → validasi → terbitkan → amati
Contoh ini memerlukan Bash, curl, jq, Node 22+, ruang kerja aktif,
tujuan Facebook Page atau LinkedIn yang terhubung, serta kunci dengan
accounts:read, posts:read, posts:write dan posts:publish. Tetapkan
ACCOUNT_ID ke tujuan yang diizinkan dari /accounts; periksa dukungan format
teksnya di /capabilities. Menjalankan perintah publish akan mem-posting konten nyata.
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"
Untuk tujuan gambar/video, unggah dan finalisasi media terlebih dahulu,
lalu gunakan ID aset yang dikembalikan dalam mediaIds dan format tujuan yang memenuhi syarat.
Amati ID pengiriman individual dari respons yang diterima; gunakan webhook atau
polling status berbatas dengan backoff. Satu pembacaan status segera bisa saja masih tertunda.
Menjadwalkan alih-alih menerbitkan
Gunakan ini pada sebuah draf alih-alih langkah publish di atas. Ambil kembali versi terkininya setelah setiap pengeditan. Ini menghitung waktu instan di masa depan alih-alih memakai tanggal contoh yang akan kedaluwarsa.
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"
Waktu instan harus di masa depan dan dalam horizon 90 hari; waktu instan UTC dan
zona waktu tampilan disimpan terpisah. Jika kunci API Anda kedaluwarsa pada atau sebelum
waktu tersebut, respons yang diterima menyertakan entri warnings dengan kode
key_expires_before_schedule. Pengiriman tetap terjadwal, tetapi harus ditinjau
dan dikirim ulang di bawah prinsipal aktif sebelum dapat diterbitkan. Peringatan yang sama
dipertahankan saat memutar ulang permintaan. Batalkan selama masih belum diambil secara aman:
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.
Coba ulang hanya tujuan yang diketahui gagal (status tidak diketahui/berhasil ditolak):
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry
Media (unggahan langsung)
Byte media tidak pernah melewati API ini.
# 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
Berkas bersifat sementara: posting terjadwal menyimpan medianya sampai penerbitan, dan
deleteAfter dinamis (atau null) selalu ditampilkan. Simpan berkas asli Anda.
Penggunaan
GET /usage melaporkan paket, slot akun terhubung/cadangan, anggota, penyimpanan,
horizon 90 hari, dan info laju. Angka aktivitas hanyalah metrik operasional:
tidak ada penghitung posting tersisa di mana pun dalam produk ini.
Paginasi
Endpoint daftar menggunakan kursor opak: ?limit=25&cursor=<nextCursor>. Stempel waktu
berformat UTC ISO-8601. Lanjutkan hingga nextCursor bernilai null; halaman posting
terfilter bisa kosong sementara kursor non-null-nya menunjuk ke rekaman lama yang masih perlu dipindai.
Utamakan webhook (lihat webhooks) atau polling berbatas dengan backoff
daripada loop status yang rapat.
Batasan dan keberhasilan parsial
Kemampuan tujuan (dari GET /capabilities) membawa batas efektif paling ketat:
aplikasi, penyedia, jaringan, dan akun. Saat sebuah batas memblokir permintaan,
amplop kesalahan dapat ditindaklanjuti:
{
"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 dan
trial_expired adalah respons 402; tidak ada yang dihapus, dan draf/pekerjaan dalam antrean
dipertahankan untuk setelah peningkatan paket.
Publish/schedule adalah kumpulan pekerjaan tujuan yang independen. Keberhasilan parsial adalah hal normal dan dilaporkan per tujuan: bukan sebagai janji atomik:
{
"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": "…"
}
Coba ulang hanya tujuan yang gagal (POST /deliveries/{id}/retry); tujuan yang
berhasil tidak pernah dikirim ulang. Persyaratan persetujuan/sambung ulang mengembalikan
requires_action dengan instruksi yang aman, bukan rahasia.
Referensi lengkap
Untuk TikTok, GET /accounts/{id}/tiktok/settings mengembalikan pilihan privasi terkini
creator yang terhubung, izin interaksi, batas durasi, dan ketersediaan mode penerbitan.
Memerlukan accounts:read dan menghormati daftar izin kunci.
Menyimpan draf atau membaca pengaturan ini tidak memberikan persetujuan.
Publish/schedule tanpa konfirmasi manusia terkini mengembalikan HTTP 409
consent_required dengan error.requiresAction.url yang menunjuk ke draf tersimpan
di komposer yang terautentikasi. Validasi dapat mengembalikan serah terima yang sama
bersama isu terstrukturnya. Orang tersebut meninjau video/takarir secara persis dan membuat
pilihan eksplisit di sana; kunci produk dan MCP tidak dapat mengonfirmasi atas namanya.
Setelah orang tersebut mengonfirmasi, coba ulang melalui layanan penerbitan bersama yang normal.
Mengedit konten atau mengubah identitas tujuan memerlukan peninjauan baru.
URL serah terima tidak memuat kunci produk, token, atau URL media yang ditandatangani dan tidak
memberi akses kepada orang yang bukan anggota ruang kerja. UUID ruang kerjanya mengidentifikasi
ruang kerja kunci; peramban dengan ruang kerja terpilih yang berbeda harus berpindah
secara eksplisit setelah pemeriksaan keanggotaan terkini sebelum meninjau draf ini.
Lihat spesifikasi OpenAPI untuk kontrak lengkap dan terkini. UI, REST dan MCP membaca layanan yang sama, sehingga menerapkan aturan ruang kerja yang sama. Hasil mencerminkan status terkini setiap permintaan; permintaan terpisah dapat mengamati pembaruan yang terjadi di antaranya.