با POST /audio/music از روی یک توصیف متنی قطعهٔ موسیقی میسازید: موسیقی پسزمینهٔ ویدیو، جینگل تبلیغ، قطعهٔ بیکلام برای پادکست یا آهنگ با کلام.
پاسخ یک فایل کامل MP3 است که یکجا میرسد؛ نیمهٔ یک آهنگ به کاری نمیآید، پس این endpoint جریانی نیست.
نمونه#
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.056 |
openrouter/google/lyria-3-pro-preview |
آهنگ کامل | $0.112 |
lyria-3.5 |
آهنگ کامل | $0.112 |
lyria-3-clip-preview |
کلیپ کوتاه، تا حدود ۳۰ ثانیه | $0.056 |
lyria-3-pro-preview |
آهنگ کامل | $0.112 |
قیمت بهازای هر قطعه است، نه توکن؛ طول توصیف روی آن اثری ندارد. برای آزمودن ایدهها از openrouter/google/lyria-3-clip-preview شروع کنید.
پارامترها#
GET /models?type=music.seed ثابت، نتیجهها به هم نزدیکترند.آهنگ با کلام#
سبک، ساز، سرعت (bpm) و نوع صدا را بنویسید و بعد متن شعر را با برچسب بخشها ([Verse]، [Chorus]) بیاورید:
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) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.