AiVideoEditor
Mulai gratis
Menu

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 mengembalikan 409 revision_conflict dengan versi terkini di error.details.currentVersion.
  • 202 dari publish/schedule berarti diterima untuk pengiriman, bukan "diterbitkan". Lacak hasil dengan GET /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.