Clipwright

API Clipwright

Satu API HTTP yang mengubah naskah menjadi video UGC dengan sinkronisasi bibir. API ini dirancang untuk digerakkan oleh agen: setiap panggilan adalah satu permintaan JSON, setiap penolakan menyebutkan langkah selanjutnya, dan tidak ada yang dipublikasikan ke mana pun. Setiap kata di halaman ini juga merupakan satu file markdown di https://clipwright.io/docs.md, dan kontrak singkat untuk agen di https://clipwright.io/llms.txt.

Autentikasi

Setiap panggilan menuju ke https://api.clipwright.io dan membawa kunci dalam satu header:

Authorization: Bearer cw_your_key_here

• Kunci dimulai dengan cw_ dan hanya ditampilkan sekali, saat diterbitkan. Kami hanya menyimpan digest, jadi kunci yang hilang diganti, tidak pernah dipulihkan.
• Terbitkan dan cabut kunci di dasbor di https://app.clipwright.io/api-keys. Pencabutan berlaku pada permintaan berikutnya.
• @clipwright/cli dan @clipwright/mcp-server membaca kunci dari variabel lingkungan CLIPWRIGHT_API_KEY; @clipwright/sdk menerimanya sebagai argumen.
• Panggilan tanpa kunci, atau dengan kunci yang dicabut, ditolak dengan 401 sebelum ada biaya apa pun.

03

Berapa biayanya

• make_ugc dari naskah biasa: 30 kredit untuk setiap detik video jadi, dibulatkan ke atas ke detik penuh.
• make_ugc dengan segmen atau sisipan: 10 kredit untuk setiap detik wajah tampil di layar, dan minimal 400 kredit untuk video yang kami kirimkan. Detik tanpa wajah tidak dikenai biaya, dan proses yang tidak menghasilkan file tidak dikenai biaya sama sekali, bahkan ketika vendor sudah dibayar. Waktu wajah dijumlahkan di seluruh video dan dibulatkan ke atas sekali, bukan per segmen. Kolom-kolom ini memerlukan kualifikasi panjang di deployment; jika nonaktif, kolom-kolom tersebut ditolak berdasarkan nama sebelum ada biaya.
• create_actor dengan kualitas medium: 10 kredit untuk potret dan 10 untuk setiap format tambahan.
• create_actor dengan kualitas high: 20 kredit untuk potret dan 20 untuk setiap format tambahan.
• Kredit dibeli dalam paket: 1000 kredit seharga $10.00, satu pembayaran, tanpa langganan.

Tanyakan sebelum Anda mengeluarkan biaya: endpoint kutipan dari kedua skill tidak dikenai biaya. Nilai jawabannya berbeda-beda tergantung skill.

• make_ugc: kutipan adalah perkiraan yang dibaca dari kata-kata naskah. Biaya mengikuti apa yang diukur dalam video jadi — durasinya pada meter naskah biasa, detik wajahnya pada meter wajah — jadi tagihan bisa lebih tinggi atau lebih rendah dari kutipan.
• create_actor: kutipan memberi harga setiap format yang Anda minta, yang merupakan jumlah maksimum yang dapat Anda bayar. Anda dikenai biaya untuk potret dan varian yang benar-benar diterbitkan; format yang tidak jadi disebutkan dalam warnings[] dan tidak dikenai biaya.

Biaya proses yang gagal juga berbeda-beda tergantung skill:

• make_ugc dari naskah biasa: proses yang gagal setelah pekerjaan pengiriman mencapai vendor dikenai biaya. Proses yang gagal sebelumnya tidak dikenai biaya, begitu juga proses yang kami hentikan, hilangkan, atau tolak sendiri, bahkan ketika vendor sudah dibayar. Pada meter wajah, tidak ada kegagalan yang dikenai biaya.
• create_actor: proses yang gagal tidak dikenai biaya sama sekali, bahkan ketika vendor sudah dibayar, karena tidak ada aktor yang sampai kepada Anda.

04

Endpoint

Endpoint	Mengenai biaya kredit	Fungsinya
GET /health	tidak	Liveness dari API itu sendiri. Menjawab tanpa kunci.
GET /v1/voices	tidak	Suara yang dapat Anda sebutkan di voice atau voice_id.
GET /v1/account	tidak	Saldo, utang, dan hold dari akun di balik kunci.
POST /v1/skills/make_ugc/quote	tidak	Memberi harga panggilan make_ugc dengan input ini. Tidak mengenakan biaya.
GET /v1/runs/{id}	tidak	Status satu proses dari skill apa pun, peringatannya, dan url videonya.
POST /v1/skills/make_ugc/run	ya	Memulai proses video dan langsung menjawab dengan run_id. Poll proses untuk hasilnya.
GET /v1/public/skills	tidak	Katalog skill dan inputnya, tanpa kunci.
GET /v1/actors	tidak	Aktor yang tersimpan di akun, dengan id yang diterima make_ugc.
DELETE /v1/actors/{id}	tidak	Melupakan aktor yang tersimpan. Aktor yang digunakan oleh proses aktif tetap dipertahankan.
GET /v1/actors/{id}/defaults	tidak	Membaca kebijakan default aktor tersimpan untuk orang di sisipan.
POST /v1/actors/{id}/defaults	tidak	Menetapkan kebijakan default aktor tersimpan untuk orang di sisipan. Proses dapat menimpanya.
POST /v1/skills/create_actor/quote	tidak	Memberi harga panggilan create_actor dengan input ini. Tidak mengenakan biaya.
POST /v1/skills/create_actor/run	ya	Memulai proses aktor dan langsung menjawab dengan run_id. Poll proses untuk hasilnya.
POST /v1/uploads	tidak	Menerima byte gambar dan mengembalikan url https yang diterima make_ugc dan create_actor.

Proses dari salah satu skill dibaca kembali dari tempat yang sama, GET /v1/runs/{id}, dan bergerak melalui status-status ini: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

05

Skill dan inputnya

make_ugc. Mulai pembuatan video UGC dengan sinkronisasi bibir. Berikan naskah dalam batas teks model ucapan yang dipilih; aktor berasal dari actor_id (aktor tersimpan dari list_actors) atau image, jika tidak, aktor default digunakan. Format dan resolusi mengikuti permintaan dan sumber, default ke 1080x1920. Teks takarir bersifat OPT-IN: tanyakan kepada pengguna terlebih dahulu. Kolom yang belum dihormati renderer membawa catatan NOT HONORED YET di deskripsinya sendiri — baca itu alih-alih menebak.

Panggil quote_ugc sebelum membuat dan tampilkan biayanya. Ini TIDAK menunggu video: ini memulai proses dan mengembalikan run_id SEGERA. Anda HARUS kemudian poll get_run dengan run_id tersebut hingga statusnya 'succeeded' (video_url) atau 'failed'. Proses 'failed' yang pekerjaan vendor berbayarnya masih kami pegang dapat kembali ke 'queued' dan mencapai 'succeeded' kemudian; kapan pun itu terjadi, ia disebutkan dalam warnings[]. Berikan attempt=2,3,… untuk sengaja memulai proses BARU untuk input yang sama (coba lagi setelah kegagalan).

Kolom	Wajib	Artinya
script	opsional	Kata-kata yang diucapkan aktor; wajib kecuali segments menyediakan teks lisan. Segmen dan sisipan berjangkar teks memerlukan kualifikasi panjang di server. Batas naskah berdasarkan model ucapan: eleven_v3: 5000 karakter; eleven_flash_v2_5: 10000 karakter; eleven_turbo_v2_5: 10000 karakter. Hitungan mencakup spasi, tag audio, dan tanda tekanan; emoji dapat dihitung sebagai dua karakter. Tidak ada batas jumlah kata. Durasi dan harga adalah perkiraan hingga diukur. Tekanan bahasa Rusia: tulis vokal bertekanan sebagai huruf kapital di dalam kata huruf kecil ("потОм", "зАмок") dan eleven_v3 menerimanya sebagai tanda tekanan U+0301 ("пото́м"); tanda yang diketik langsung dipertahankan. Huruf kapital di awal kata tetap huruf kapital, dan kata dengan huruf kapital kedua atau konsonan kapital di dalamnya (semua kapital, "ВУЗы") dibiarkan apa adanya. Satu vokal kapital di dalam kata selalu dibaca sebagai tekanan, jadi tulis "Яндекс Еда", bukan "ЯндексЕда". Beri tahu pengguna yang menulis dalam bahasa Rusia bahwa mereka dapat menandai tekanan dengan cara ini. eleven_flash_v2_5 dan eleven_turbo_v2_5 lebih murah tetapi salah membaca tanda tekanan: huruf kapital sampai kepada mereka tanpa perubahan.
segments	opsional	Segmen aktor dan gambar yang berurutan; memerlukan kualifikasi panjang di server, captions=false dan 1080p. Media gambar memerlukan broll_policy=anyone yang eksplisit.
inserts	opsional	Sisipan gambar berjangkar teks di atas narasi penuh, masing-masing mencakup cover_words kata lisan dari jangkarnya; memerlukan kualifikasi panjang di server, captions=false, 1080p dan broll_policy=anyone yang eksplisit.
person	opsional	NOT HONORED YET: person belum dihormati: permintaan ini menggunakan aktor default; pilih actor_id dari list_actors atau berikan image untuk memilih wajah yang berbeda
actor_id	opsional	ID aktor Clipwright tersimpan dari list_actors. Pilih actor_id, image, atau person; jangan gabungkan. Tanpa voice atau voice_id, suara mengikuti jenis kelamin aktor. Jangan gabungkan dengan actor_gender.
image	opsional	Url https publik dari foto aktor (PNG, JPEG atau WebP, hingga 10 MB). File di disk melalui upload_image (POST /v1/uploads) terlebih dahulu — berikan url yang dikembalikannya. Sumber yang tidak dapat kami gunakan — host privat atau loopback, http, tidak dapat dijangkau, mengalihkan, lebih dari 10 MB, atau bukan salah satu jenis gambar tersebut — ditolak (unusable_source) sebelum ada biaya. Kami tidak mendeteksi jenis kelamin wajah: berikan actor_gender atau voice, atau suara pria default digunakan dengan peringatan.
actor_gender	opsional	Jenis kelamin wajah di image: female | male. Hanya dengan image: memilih suara default dari jenis kelamin tersebut (female: sarah, male: george). Ditolak dengan actor_id (jenis kelaminnya diketahui) dan tanpa image. voice atau voice_id yang eksplisit menang dan respons memperingatkan bahwa actor_gender tidak mengubah apa pun.
name	opsional	NOT HONORED YET: name belum dihormati: tidak mencapai renderer
broll_policy	opsional	HANYA DISIMPAN: Kebijakan tersimpan untuk B-roll: anyone mengizinkan orang termasuk aktor; no_actor mengecualikan aktor; no_people mengecualikan semua orang, termasuk tangan. Pembuatan media bersegmen ditutup. Pengaturan ini hanya disimpan dan tidak berpengaruh pada video hanya-aktor. Penimpaan proses menang atas default aktor akun; jika tidak, no_people.
captions	opsional	NOT HONORED YET: captions diminta tetapi tidak dirender dalam prototipe ini (tahap-B)
caption_style	opsional	NOT HONORED YET: caption_style tidak dihormati: captions tidak dirender dalam prototipe ini (tahap-B)
look	opsional	NOT HONORED YET: look belum dihormati: tidak mencapai renderer
aspect_ratio	opsional	Format keluaran: 9:16 | 1:1 | 16:9. Dihilangkan berarti 9:16, dan sumber dengan bentuk lain dijepret ke 9:16 dengan peringatan — berikan secara eksplisit setiap kali Anda memberikan image. Ketidakcocokan di atas 15% antara permintaan dan sumber ditolak (aspect_conflict) sebelum ada biaya.
resolution	opsional	Resolusi keluaran: 720p | 1080p | 4k (sisi pendek 720 / 1080 / 2160 px). Dihilangkan berarti 1080p.
voice	opsional	Nama suara dari list_voices. Prasetel kurasi: owner_ru_clone | sarah | george | eric | daria_ru_female (owner_ru_clone adalah suara kloning bahasa Rusia). API menolak nama yang tidak dikembalikan list_voices, sebelum ada biaya. Dihilangkan berarti suara default untuk jenis kelamin aktor: jenis kelamin actor_id, actor_gender dengan image, atau george untuk aktor default dan untuk image tanpa actor_gender. Saling eksklusif dengan voice_id.
voice_id	opsional	Id suara vendor mentah (16–32 huruf dan angka) untuk suara di luar katalog. Diperiksa secara lambat: id yang tidak dikenal menggagalkan proses, bukan permintaan. Saling eksklusif dengan voice.
tts_model	opsional	Model ucapan: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5. Dihilangkan berarti model dari prasetel yang dipilih (list_voices menampilkannya; setiap prasetel berbicara eleven_v3) atau eleven_v3 untuk voice_id mentah. eleven_v3 adalah yang paling ekspresif dan satu-satunya yang membaca tanda tekanan (vokal kapital di dalam kata Rusia, "потОм", menjadi satu; lihat script); eleven_flash_v2_5 dan eleven_turbo_v2_5 adalah alternatif lebih murah untuk bahasa selain Rusia. Batas naskah berdasarkan model ucapan: eleven_v3: 5000 karakter; eleven_flash_v2_5: 10000 karakter; eleven_turbo_v2_5: 10000 karakter. Hitungan mencakup spasi, tag audio, dan tanda tekanan; emoji dapat dihitung sebagai dua karakter. Tidak ada batas jumlah kata. Durasi dan harga adalah perkiraan hingga diukur.
disclosure_overlay	opsional	Nilai yang diterima: true | false.
background	opsional	Nilai yang diterima: white | blur | contain.

create_actor. Buat aktor pribadi untuk akun ini dari kata-kata yang menggambarkan orang dewasa fiktif: potret 9:16 dengan tepat satu wajah, plus format lain yang diminta yang diedit darinya. Mengembalikan run_id segera; poll get_run hingga 'succeeded' (created_actor.actor_id, lalu berikan sebagai actor_id ke make_ugc) atau 'failed'. Setiap gambar yang diterbitkan dikenai biaya sesuai yang ditunjukkan kutipan harga; deskripsi yang ditolak dan potret yang tidak dapat digunakan tidak dikenai biaya. Ketika pembuatan dimatikan, panggilan gagal dengan actor_generation_disabled.

Bidang	Wajib	Artinya
description	wajib	Kata-kata yang menggambarkan karakter dewasa fiktif: penampilan, pakaian, latar. Menyebutkan orang nyata atau kemiripan dengan orang nyata ditolak sebelum ada biaya (actor_prompt_refused).
gender	wajib	female | male. Menetapkan jenis kelamin karakter dan suara default video dengan karakter ini.
approximate_age	wajib	Perkiraan usia dalam tahun, 18 hingga 90: karakter adalah orang dewasa.
name	wajib	Nama yang ditampilkan di list_actors.
aspect_ratios	opsional	Format yang dibuat: 9:16 | 1:1 | 16:9, selalu menyertakan 9:16. Jika dihilangkan berarti ketiganya. Format yang gagal dalam pemeriksaan identitas tidak dikenakan biaya dan disebutkan dalam peringatan.
quality	opsional	Kualitas gambar: medium | high. Jika dihilangkan berarti medium. Harga per gambar bergantung padanya; kutipan menampilkannya sebelum ada biaya.

Format keluaran mengikuti permintaan dan sumber. Format yang didukung adalah 9:16, 1:1, 16:9 dan resolusi 720p, 1080p, 4k; jika tidak disebutkan berarti 1080p dalam 9:16.

06

Memulai proses

Panggilan berbayar membawa satu header selain kunci: Idempotency-Key. POST /v1/skills/make_ugc/run dan POST /v1/skills/create_actor/run memerlukannya, dan panggilan tanpa itu ditolak dengan 400 idempotency_key_required sebelum ada yang dikenakan biaya.

• Anda memilih kunci, dan itu satu-satunya hal yang membedakan percobaan ulang dari pesanan kedua. String unik apa pun bisa digunakan; simpan selama Anda mungkin mengirim ulang panggilan.
• Kunci yang sama dengan isi yang sama mengembalikan proses yang sudah dimulai dan tidak mengenakan biaya untuk kedua kalinya. Itulah yang membuat percobaan ulang biasa aman.
• Kunci yang sama dengan isi yang berbeda ditolak dengan 409 idempotency_key_reused. Gunakan kunci baru untuk permintaan baru alih-alih mengedit permintaan di bawah kunci yang sudah digunakan.
• Untuk memulai proses baru yang disengaja pada masukan yang sama — percobaan ulang setelah kegagalan — kirim kunci baru. Proses yang sudah Anda bayar tetap di tempatnya.
• @clipwright/sdk dan @clipwright/mcp-server membuat kunci untuk Anda dari klien dan masukan, dan mengubah attempt=2, 3 … menjadi kunci baru. Melalui HTTP biasa, kunci terserah Anda untuk memilih.

07

Saat panggilan gagal

Setiap penolakan membawa objek kesalahan dengan kode dan pesan. Apa yang harus dilakukan mengikuti jenis penolakan, bukan teksnya:

Penolakan	HTTP	Ulangi panggilan yang sama?	Apa yang harus dilakukan
rate_limited	429	ya, setelah menunggu	Tekanan balik, bukan kesalahan: respons menyebutkan detik untuk menunggu, di Retry-After dan di isi.
server_error	500, 502, 503	ya, setelah menunggu	Kegagalan ada di sisi server. Jangan mulai proses kedua dengan kunci idempotensi baru: panggilan yang sama adalah percobaan ulang.
insufficient_credits	402	tidak, itu memberikan jawaban yang sama	Berhenti dan beri tahu orang tersebut saldo dan harga; keduanya ada di isi. Mengulang tidak dapat mengubah keduanya.
debt_outstanding	402	tidak, itu memberikan jawaban yang sama	Berhenti. Membeli kredit membersihkan utang sebelum apa pun mencapai saldo, dan itu menghapus blokir.
not_admitted	403	tidak, itu memberikan jawaban yang sama	Berhenti. Akun tidak memiliki akses beta; baik percobaan ulang maupun pembelian tidak mengubah itu. Tanyakan operator.
client_error	400, 401, 404, 409, 413, 415	tidak, itu memberikan jawaban yang sama	Berhenti. Permintaan itu sendiri ditolak: baca pesannya, perbaiki panggilan, lalu kirim lagi.

Ini semua adalah kode yang API masukkan ke error.code. Kode yang belum pernah Anda lihat tetap mengikuti barisnya di atas, karena baris dipilih berdasarkan status:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

Batasan

• 60 permintaan berbayar dan 300 permintaan gratis per 60 detik. Jendela dihitung per akun, bukan per kunci, jadi kunci tambahan tidak membeli throughput tambahan.
• 3 render berjalan sekaligus per akun; sisanya mengantre dan tidak ditolak.
• Penolakan karena batas kecepatan menyebutkan detik untuk menunggu di Retry-After dan di isi. Hormati yang lebih besar dari keduanya.
• 49 sisipan per klip, dan paling banyak 6 kemunculan karakter di antaranya. Keduanya dihitung dari indeks kata yang Anda kirim, jadi masukan yang meminta lebih ditolak sebelum ada yang dibayar.
• cover_words mengatakan berapa banyak kata lisan yang dicakup oleh sisipan, dihitung dari kata pertama jangkarnya. Sisipan berakhir di mana kata pertama yang tidak tercakup dimulai, jadi dua sisipan yang cakupannya bertemu bersebelahan dan tidak menyisakan bidikan karakter di antaranya.
• Bagian kata yang Anda biarkan tidak tercakup menentukan bagian klip yang menampilkan wajah, dan itu tidak bergerak dengan kecepatan suara. Panjang kata memang bervariasi: pada skrip 560 kata, meminta 19% menghasilkan 16 hingga 22 dalam sembilan ratus sembilan puluh tujuh dari seribu simulasi, dan tetap dalam 15 hingga 24 dalam lima puluh ribu. Angka-angka itu diukur pada suara profil ini dan pada panjang itu; skrip yang lebih pendek menyebar lebih lebar, dan suara yang berbeda menggesernya.
• Dua pilihan satu kata mengubah harga, bukan hanya tampilan. Sisipan yang berjangkarkan kata 0 memiliki keheningan sebelum kata pertama; berjangkarkan kata 1 meninggalkan kemunculan ekstra karakter, dan setiap kemunculan adalah pekerjaan berbayar terpisah. Cakupan yang mencapai kata terakhir membawa klip ke akhirnya dan menghapus kemunculan penutup dengan cara yang sama.
• Kutipan melaporkan bagian sebagai estimatedFaceWordShare. Baca bidang itu; jangan bagi estimatedFaceSeconds dengan estimatedTotalDurationSec. Keduanya menjawab pertanyaan yang berbeda — yang pertama adalah cadangan yang kami pegang di ujung lambat rentang bicara, yang kedua adalah berapa lama klip diharapkan berjalan — dan rasionya bukan bagian dari apa pun.

09

Apa yang API ini tidak akan pernah lakukan

• Menerbitkan apa pun. Kami mengembalikan file dan tautan bertanda tangan; ke mana ia pergi terserah Anda.
• Membatalkan proses yang sudah dimulai. Tidak ada endpoint untuk itu: setelah vendor memiliki pekerjaan, menghentikannya di sisi kami tidak akan membatalkan biayanya.
• Menerima bidang ini: character, broll_url, webhook_url. Mereka ditolak berdasarkan nama sebelum ada biaya, bukan diterima dan diabaikan diam-diam.
• Mengubah format atau resolusi yang Anda minta tanpa mengatakannya. Ketidakcocokan di-snap dengan peringatan atau ditolak sebelum panggilan berbayar.
• Menghubungi Anda kembali. Tidak ada webhook: baca proses dengan GET /v1/runs/{id}.
• Menampilkan kunci untuk kedua kalinya, atau memulihkannya dari cadangan.

10

Juga perlu diketahui

• Peringatan, bukan keheningan. Apa pun yang tidak dapat kami penuhi kembali dalam warnings[] pada proses yang sama, dengan nama. Parameter tidak pernah hilang tanpa baris tentangnya.
• Server MCP. @clipwright/mcp-server mengekspos kontrak yang sama sebagai alat, dan tools/list-nya adalah bentuk yang dapat dibaca mesin dari halaman ini.