با POST /audio/music از روی یک توصیف متنی قطعهٔ موسیقی میسازید: موسیقی پسزمینهٔ ویدیو، جینگل تبلیغ، قطعهٔ بیکلام برای پادکست یا آهنگ با کلام.
پاسخ یک فایل کامل MP3 است که یکجا میرسد؛ نیمهٔ یک آهنگ به کاری نمیآید، پس این endpoint جریانی نیست.
نمونه
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
curl https://gisoo.pro/api/v1/audio/music \
-H "Authorization: Bearer $GISOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openrouter/google/lyria-3-clip-preview",
"prompt": "Calm lo-fi piano with soft rain in the background, slow tempo, no vocals"
}' | jq -r '.data[0].b64_json' | base64 --decode > calm.mp3
import base64, os, requests
res = requests.post(
"https://gisoo.pro/api/v1/audio/music",
headers={"Authorization": f"Bearer {os.environ['GISOO_API_KEY']}"},
json={
"model": "openrouter/google/lyria-3-clip-preview",
"prompt": "Upbeat acoustic guitar jingle for a coffee shop ad, 30 seconds, no vocals",
},
timeout=120,
)
res.raise_for_status()
track = res.json()
with open("jingle.mp3", "wb") as f:
f.write(base64.b64decode(track["data"][0]["b64_json"]))
print(track["text"]) # e.g. <instrumental>, or the lyrics the model sang
import fs from "node:fs";
const res = await fetch("https://gisoo.pro/api/v1/audio/music", {
method: "POST",
headers: { Authorization: "Bearer " + process.env.GISOO_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ model: "openrouter/google/lyria-3-clip-preview", prompt: "Ambient synth pad for meditation, no drums" }),
});
const track = await res.json();
fs.writeFileSync("ambient.mp3", Buffer.from(track.data[0].b64_json, "base64"));
{
"id": "req_2f8a91c4b7e0d3a6c5f1e2b9",
"object": "music.generation",
"created": 1790000000,
"model": "openrouter/google/lyria-3-clip-preview",
"text": "<instrumental>",
"data": [
{ "b64_json": "SUQzBAAAAAAA…", "format": "mp3", "bytes": 744608 }
]
}
data[0].b64_jsonخود فایل است؛ decode و ذخیره کنید.formatقالب فایل وbytesحجم آن است.textبرچسبی مثل<instrumental>برای قطعهٔ بیکلام، یا متنی که مدل خوانده است.- SDK رسمی OpenAI متدی برای این endpoint ندارد؛ با یک درخواست HTTP معمولی (مثل نمونهها) صدایش بزنید.
مدلها
| model | خروجی | قیمت هر قطعه (دلار) |
|---|---|---|
openrouter/google/lyria-3-clip-preview |
کلیپ کوتاه، تا حدود ۳۰ ثانیه | $0.0611 |
openrouter/google/lyria-3-pro-preview |
آهنگ کامل | $0.1223 |
lyria-3.5 |
آهنگ کامل | $0.112 |
lyria-3-clip-preview |
کلیپ کوتاه، تا حدود ۳۰ ثانیه | $0.056 |
eleven-music-v1 |
قطعهٔ موسیقی، ۳ تا ۳۰۰ ثانیه | بهازای طول قطعه |
eleven-sound-effects-v2 |
جلوه صوتی، ۰٫۵ تا ۳۰ ثانیه | بهازای طول قطعه |
lyria-3-pro-preview |
آهنگ کامل | $0.112 |
eleven-sound-effects-v3 |
جلوه صوتی، ۰٫۵ تا ۳۰ ثانیه | بهازای طول قطعه |
قیمت مدلهای Lyria بهازای هر قطعه است، نه توکن؛ طول توصیف روی آن اثری ندارد. برای آزمودن ایدهها از openrouter/google/lyria-3-clip-preview شروع کنید.
مدلهای ElevenLabs (eleven-music-v1، eleven-sound-effects-v2 و eleven-sound-effects-v3) را هم با همین endpoint صدا میزنید، ولی هزینهشان بهازای طول قطعه است: طول را با seconds خودتان تعیین میکنید و پاسخ، همان مقدار را در data[0].seconds برمیگرداند. نمونه
پارامترها
GET /models?type=music.seed ثابت، نتیجهها به هم نزدیکترند. روی مدلهای ElevenLabs اثر ندارند.eleven-music-v1 از ۳ تا ۳۰۰ (پیشفرض ۳۰)، مدلهای جلوهٔ صوتی از ۰٫۵ تا ۳۰ (پیشفرض ۵).آهنگ با کلام
سبک، ساز، سرعت (bpm) و نوع صدا را بنویسید و بعد متن شعر را با برچسب بخشها ([Verse]، [Chorus]) بیاورید:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
track = requests.post(
"https://gisoo.pro/api/v1/audio/music",
headers={"Authorization": f"Bearer {os.environ['GISOO_API_KEY']}"},
timeout=120,
json={
"model": "openrouter/google/lyria-3-pro-preview",
"prompt": (
"Warm Persian pop ballad, female vocal, acoustic guitar and soft strings, 90 bpm.\n"
"Lyrics:\n"
"[Verse] The city sleeps, the tea is warm...\n"
"[Chorus] Stay a little longer..."
),
},
).json()
مدل متن فارسی را میپذیرد، ولی تلفظ و وزن آواز فارسی هنوز به خوبی انگلیسی نیست. پیش از استفادهٔ جدی، چند نسخه بسازید و آن را که بیشتر میپسندید نگه دارید.
نکتهها
- کلیپ کوتاه معمولاً در چند ثانیه آماده میشود، ولی آهنگ کامل ممکن است تا حدود یک دقیقه و نیم طول بکشد؛ زمان انتظار کلاینت HTTP را دستکم ۱۲۰ ثانیه بگذارید.
- اگر ساخت قطعه ناموفق باشد یا فایلی برنگردد، هزینهای کم نمیشود.
- مدلهای موسیقی را به
/chat/completionsنفرستید؛ خطایmodel_endpoint_mismatchمیگیرید. - حق استفاده از خروجی تابع شرایط سازندهٔ مدل است؛ برای استفادهٔ تجاری، شرایط همان سازنده را بخوانید.
پاسخ پرسشتان را پیدا نکردید؟
شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.