Musik
Buat lagu utuh dari lirik, atau trek instrumental dari deskripsi teks. Response-nya objek JSON yang membawa audio dalam base64. Hanya model musik yang dilayani di sini. Mengirim model lain mengembalikan 400.
POST /v1/music/generations
Model musik ditandai dengan music pada field endpoints di GET /v1/models:
curl -s https://kenari.id/v1/models \ | jq '.data[] | select(.endpoints | index("music")) | {id, formats, max_lyrics_chars, max_prompt_chars, max_duration_secs, pricing_lines}'Kalau panggilan itu tidak mengembalikan apa pun, saat ini belum ada model musik yang tersedia.
Ada dua jenis model musik, dan formats pada entri model menunjukkan jenisnya:
["mp3"]: lagu dengan vokal dibuat darilyrics, dan trek instrumental dariprompt.["m4a", "wav"]: setiap trek dibuat dariprompt, yaitu gaya dan suasananya.lyricsmenambahkan kata-kata untuk dinyanyikan.
Halaman ini menyebut keduanya model mp3 dan model m4a.
Request
Section titled “Request”Body-nya JSON.
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
model | string | ya | Id model musik. |
lyrics | string | bersyarat | Kata-kata yang dinyanyikan. Pada model mp3, wajib untuk lagu dengan vokal, yaitu saat instrumental bernilai false atau tidak diisi. Opsional pada model m4a. |
prompt | string | bersyarat | Gaya dan suasana trek. Pada model mp3, wajib saat instrumental bernilai true dan opsional pada lagu dengan vokal. Selalu wajib pada model m4a. |
instrumental | boolean | tidak | true membuat trek tanpa vokal. Default false. Saat true, model mp3 mengabaikan lyrics, sedangkan model m4a mengembalikan 400 kalau lyrics dikirim. |
response_format | string | tidak | Salah satu nilai di formats model: mp3 pada model mp3, m4a atau wav pada model m4a. Kosongkan untuk mendapat nilai pertama. Nilai lain mengembalikan 400. |
stream | boolean | tidak | Dicadangkan. true mengembalikan 400. |
lyrics_optimizer | boolean | tidak | Dicadangkan. true mengembalikan 400. |
Response
Section titled “Response”Lagunya ada di data[0].b64_json, dan formatnya di data[0].format:
{ "data": [ { "b64_json": "<base64 dari byte audio>", "format": "mp3" } ]}data selalu berisi tepat satu item. format adalah format audio yang kamu terima: mp3, m4a atau wav. Audio bukan tautan unduhan, jadi decode base64-nya lalu tulis ke file dengan ekstensi itu.
Karena pembuatan lagu lambat, body bisa datang dalam dua bentuk.
- Spasi di awal. Selama lagu dibuat, gateway menulis satu spasi setiap 20 detik untuk menjaga koneksi tetap terbuka, lalu mengirim JSON-nya. Parse seluruh body sebagai JSON, yang mengabaikan spasi di awal. Jangan perlakukan sebagai audio mentah.
- Error yang terlambat. Kegagalan di awal tetap memakai status aslinya:
400,402,429atau503. Kegagalan setelah gateway terlanjur mengirim200datang sebagai HTTP200dengan objek error standar, misalnya{"error": {"code": "...", "message": "...", "param": null, "type": "..."}}. Selalu periksa fielderrorsebelum mendecode audio.
Lirik atau deskripsi
Section titled “Lirik atau deskripsi”lyrics adalah teks yang dinyanyikan, bukan deskripsi lagu. Mengirim “lagu pop santai tentang Jakarta” sebagai lyrics membuat model menyanyikan kalimat itu. Tulis deskripsi lagu di prompt. Pada model mp3, trek yang hanya punya deskripsi perlu instrumental bernilai true.
Penanda bagian membantu model menyusun lagu:
[Verse]Lampu kota menyala satu per satuAku pulang membawa cerita baru
[Chorus]Malam ini milik kitaSampai pagi tibaBatas panjang
Section titled “Batas panjang”Panjang dihitung dalam karakter Unicode, bukan byte, jadi teks beraksen tidak terpotong lebih cepat dari yang terlihat. Batasnya berbeda per model. Kalau sebuah model mencatatnya, GET /v1/models menampilkan max_lyrics_chars dan max_prompt_chars pada entrinya. Tanpa field itu, berlaku batas bawaan: 3.500 karakter untuk lyrics dan 2.000 untuk prompt pada model mp3, serta 10.000 untuk masing-masing pada model m4a. Teks yang melewati batas dijawab 400 sebelum ada biaya yang terpotong.
Panjang lagu
Section titled “Panjang lagu”Panjang lagu ditentukan oleh modelnya. Tidak ada field durasi, jadi kamu tidak bisa meminta lagu yang lebih pendek atau lebih panjang. Kalau modelnya mencatatnya, max_duration_secs di GET /v1/models memberi panjang lagu maksimum dalam detik. Angka itu hanya informasi: tidak ada request yang ditolak karenanya, dan lagu sebenarnya biasanya lebih pendek.
Waktu pembuatan
Section titled “Waktu pembuatan”Sebagian besar lagu memerlukan dua sampai tiga menit, dan lagu yang lebih panjang memerlukan waktu lebih lama. Gateway menjaga koneksi tetap terbuka dan menunggu sampai 15 menit sebelum menyerah. Atur timeout klien minimal 5 menit, dan nilai longgar seperti 15 menit paling aman. Klien yang berhenti di 3 menit sesekali akan membatalkan lagu yang sebentar lagi selesai.
Contoh
Section titled “Contoh”Baris pertama memilih satu model musik dari daftar. Isi MODEL sendiri kalau kamu sudah tahu id-nya. Contoh di bawah mengirim lyrics dan prompt sekaligus, yang berlaku untuk kedua jenis model musik, lalu menyimpan file dengan ekstensi dari format.
MODEL=$(curl -s https://kenari.id/v1/models \ | jq -r '[.data[] | select(.endpoints | index("music"))][0].id')
curl https://kenari.id/v1/music/generations \ -H "Authorization: Bearer $KENARI_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"$MODEL\", \"prompt\": \"city pop hangat, vokal perempuan\", \"lyrics\": \"[Verse]\nLampu kota menyala satu per satu\n\n[Chorus]\nMalam ini milik kita\" }" \ --max-time 900 \ -o response.json
# Berhenti jika ada objek error, lalu decode hanya string audio yang tidak kosongjq -e 'has("error") | not' response.json > /dev/null || { jq .error response.json; exit 1; }FORMAT=$(jq -r '.data[0].format' response.json)jq -er '.data[0].b64_json | select(type == "string" and length > 0)' response.json | base64 -d > "song.$FORMAT"Trek instrumental:
curl https://kenari.id/v1/music/generations \ -H "Authorization: Bearer $KENARI_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"$MODEL\", \"instrumental\": true, \"prompt\": \"lo-fi santai, piano lembut, hujan malam\" }" \ --max-time 900 \ -o response.json
jq -e 'has("error") | not' response.json > /dev/null || { jq .error response.json; exit 1; }FORMAT=$(jq -r '.data[0].format' response.json)jq -er '.data[0].b64_json | select(type == "string" and length > 0)' response.json | base64 -d > "instrumental.$FORMAT"Python
Section titled “Python”Tidak ada method SDK OpenAI untuk musik, jadi pakai requests.
import base64import os
import requests
headers = {"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"}
models = requests.get("https://kenari.id/v1/models", timeout=30).json()["data"]model = next(m["id"] for m in models if "music" in m["endpoints"])
response = requests.post( "https://kenari.id/v1/music/generations", headers=headers, json={ "model": model, "prompt": "city pop hangat, vokal perempuan", "lyrics": "[Verse]\nLampu kota menyala satu per satu\n\n[Chorus]\nMalam ini milik kita", }, timeout=900,)body = response.json() # spasi di awal diabaikan
if "error" in body: raise RuntimeError(body["error"]["message"])
song = body["data"][0]with open(f"song.{song['format']}", "wb") as f: f.write(base64.b64decode(song["b64_json"]))JavaScript
Section titled “JavaScript”import fs from "node:fs";
const headers = { Authorization: `Bearer ${process.env.KENARI_API_KEY}`, "Content-Type": "application/json",};
const { data: models } = await (await fetch("https://kenari.id/v1/models")).json();const model = models.find((m) => m.endpoints.includes("music")).id;
const response = await fetch("https://kenari.id/v1/music/generations", { method: "POST", headers, body: JSON.stringify({ model, prompt: "city pop hangat, vokal perempuan", lyrics: "[Verse]\nLampu kota menyala satu per satu\n\n[Chorus]\nMalam ini milik kita", }), signal: AbortSignal.timeout(900_000),});const body = JSON.parse(await response.text()); // spasi di awal diabaikan
if (body.error) throw new Error(body.error.message);
const song = body.data[0];fs.writeFileSync(`song.${song.format}`, Buffer.from(song.b64_json, "base64"));Penagihan
Section titled “Penagihan”Musik ditagih dengan harga tetap per lagu, berapa pun panjangnya. Pembuatan yang gagal tidak ditagih. Harga per lagu setiap model ada di Model & harga. Selengkapnya ada di Cara penagihan.
| Status | Kode | Kapan |
|---|---|---|
| 400 | bad_request | Model bukan model musik, field yang diwajibkan untuk jenis trekmu tidak ada, lyrics atau prompt melewati batas, atau response_format bukan salah satu nilai di formats model. |
| 402 | insufficient_balance | Saldo tidak cukup untuk harga satu lagu. |
| 429 | rate_limit_exceeded | Batas pembuatan musik bersamaan untuk akunmu tercapai. Lihat Batas laju. Tunggu sesuai header Retry-After, lalu coba lagi. Tidak ada biaya yang terpotong. |
| 503 | all_providers_failed, upstream_error | Tidak ada provider yang bisa membuat lagunya. Tidak ada biaya yang terpotong. Coba lagi. |
Error setelah gateway mengirim 200 datang di dalam body response. Lihat Response. Kode lainnya ada di Error.