Clipping Engine

Clipping Engine adalah sisi video dari Mager API. Engine yang sama di balik Mager Klip: beri video panjang, dan ia mencari bagian yang layak disimpan.

Apa yang bisa dilakukan

Ketiganya asinkron. Anda langsung menerima job id dan pekerjaannya berjalan di latar belakang — ini job video, bukan generasi gambar.

Semuanya butuh scope CLIPPING pada API key Anda. Key yang diterbitkan sebelum Clipping Engine ada tidak membawanya, dan panggilannya gagal dengan 403. Buat key baru untuk memakainya.

Memotong klip

Beri sebuah video dan rentang yang ingin ditinjau. AI membaca transkrip dan rekamannya, memilih momen terkuat, lalu merender masing-masing secara vertikal dengan subtitle yang sudah menyatu.

curl https://api.mageran.ai/api/v1/clips \
  --header 'x-mager-api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start_time": "00:00:00",
    "end_time": "00:20:00",
    "clip_count": 3,
    "clip_length": "30-90s",
    "target_resolution": "1080p",
    "video_duration_seconds": 3120,
    "callback_url": "https://client.example.com/webhooks/mager"
  }'

clip_count adalah jumlah klip yang dipotong, clip_length durasi target masing-masing. user_prompt mengarahkan pemilihannya — "prefer moments with a strong opening line" adalah contoh arahan yang bekerja dengan baik.

Subtitle menyala secara bawaan. Objek subtitle mengatur gaya font, ukuran, penempatan, warna, dan berapa kata yang tampil sekaligus, ditambah allowed_editing_styles — preset framing yang boleh dipilih renderer (STATIC_CROP, DYNAMIC_CROP, BLURRED_WINGS, dan lainnya).

video_duration_seconds wajib diisi: dari situlah engine mengukur besar job sebelum menyentuh videonya.

Menyusun highlight reel

Arahkan ke rekaman pertandingan. AI menilai tiap momen, menyatukan yang terbaik menjadi satu reel, dan — jika Anda mengirim template_id — merender reel itu dengan sebuah template.

curl https://api.mageran.ai/api/v1/highlights \
  --header 'x-mager-api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "Persija vs Persib",
    "category": "soccer",
    "duration": "5400",
    "start_time": "00:00:00",
    "end_time": "01:00:00",
    "layout": "SQUARE_BLUR",
    "target_resolution": "1080p"
  }'

Analisis dibatasi pada satu jam pertama rekaman. Sumber yang lebih panjang tetap diterima; hanya satu jam pertama yang dinilai.

Job yang selesai mengembalikan dua video: rawVideoUrl adalah reel yang tersusun, templatedVideoUrl adalah hasil render dengan template. Tanpa template_id, hanya reel mentah yang dihasilkan.

Membuat transkrip

Transkripsi tersedia secara mandiri, tanpa memotong apa pun.

curl https://api.mageran.ai/api/v1/transcriptions \
  --header 'x-mager-api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start_time": "00:00:00",
    "end_time": "00:10:00"
  }'

Kirim salah satu: video_url untuk video YouTube atau s3_key untuk media yang sudah ada di penyimpanan Mager — tepat satu, jangan keduanya.

Memeriksa sebuah job

Setiap panggilan pembuatan mengembalikan format yang sama:

{
  "task_id": "cmclip01hxyz123",
  "status": "running",
  "billing": { "base_moods": 1, "charged_moods": 2, "extra_moods_charged": 2 },
  "output": null,
  "result": []
}

Satu endpoint membaca semuanya kembali, apa pun panggilan yang membuat job tersebut:

curl https://api.mageran.ai/api/v1/jobs/cmclip01hxyz123 \
  --header 'x-mager-api-key: YOUR_API_KEY'

Statusnya sama dengan empat status pada generation task: queued, running, finished, failed. Dua yang terakhir bersifat final.

Membaca output

Job video mengembalikan data, bukan file, jadi hasilnya datang di output, bukan result. Nilainya null sampai job selesai.

{
  "task_id": "cmclip01hxyz123",
  "status": "finished",
  "output": {
    "segments": 128,
    "captions": [
      {
        "text": "the first thing we got wrong was pricing",
        "start": 12.4,
        "end": 15.1,
        "words": [{ "word": "the", "start": 12.4, "end": 12.55, "score": 0.99 }]
      }
    ]
  }
}

Isinya bergantung pada apa yang Anda minta:

• clips — daftar klip, masing-masing dengan judul, timing, skor viralitas, dan URL videonya
• highlights — rawVideoUrl dan templatedVideoUrl
• transcriptions — segments dan captions

Soal waktu, dan kenapa webhook lebih baik

Transkripsi audio sepuluh menit memakan waktu beberapa menit. Job klip pada sumber dua jam jauh lebih lama — videonya harus diunduh, ditranskrip, dianalisis, lalu dirender.

Isi callback_url dan biarkan webhook yang memberi tahu. Pengirimannya ditandatangani persis seperti webhook generation task, jadi kode verifikasi yang sama menangani keduanya.

Kalau tetap melakukan polling, lakukan tiap 15–30 detik. Tiap tiga detik hanya menghabiskan rate limit Anda untuk angka yang belum bergerak.

Caching

Mentranskrip video, rentang, dan kualitas yang sama untuk kedua kalinya jauh lebih cepat — hasilnya di-cache dan dipakai bersama oleh pipeline klip. Job klip pada video yang sudah pernah Anda transkrip melewati langkah itu sepenuhnya.

Biayanya

Setiap operasi berbiaya sejumlah mood tetap dikalikan pengali harga akun Anda. Nilai bawaannya 1 mood per operasi, tidak peduli sepanjang apa videonya. Lihat Moods and billing untuk cara kerja pengalinya.

"billing": { "base_moods": 1, "charged_moods": 2, "extra_moods_charged": 2 }

Job yang tidak pernah mulai, atau gagal secara permanen, dikembalikan penuh. Berbeda dengan generation task, tidak ada yang ditahan.

Kirim idempotency_key pada panggilan pembuatan mana pun agar retry menjadi aman: panggilan ulang mengembalikan job yang asli, bukan menjalankan dan menagih untuk kedua kalinya.

Selanjutnya