POST /api/ai/v1/audio/music نیازمند کلید API

ساخت قطعهٔ موسیقی از روی توصیف متنی، با مدل‌های Lyria 3 گوگل. خروجی یک فایل MP3 استریو ۴۸ کیلوهرتز است که در قالب base64 برمی‌گردد. فهرست مدل‌ها و قیمت هر قطعه در صفحهٔ مدل‌ها.

چرا endpoint جداگانه دارد

مدل موسیقی از نظر ارائه‌دهنده یک مدل گفت‌وگوست که به‌جای متن، صدا برمی‌گرداند و فقط به شکل استریم جواب می‌دهد. درگاه همان استریم را باز می‌کند، تا آخر می‌خواند و یک فایل کامل به شما می‌دهد — چون نصفِ یک آهنگ به درد کسی نمی‌خورد. پس مدل‌های موسیقی را به /chat/completions نفرستید؛ خطای model_endpoint_mismatch می‌گیرید.

درخواست

Python

import base64, httpx

res = httpx.post(
    "https://netarz.ir/api/ai/v1/audio/music",
    headers={"Authorization": f"Bearer {NETARZ_API_KEY}"},
    json={
        "model": "openrouter/google/lyria-3-clip-preview",
        "prompt": "قطعهٔ آرام لو‌فای با پیانو، تمپوی کند، حال‌وهوای امیدوار، بدون کلام",
    },
    timeout=180,
).json()

open("clip.mp3", "wb").write(base64.b64decode(res["data"][0]["b64_json"]))

Node.js

import { writeFile } from "node:fs/promises";

const res = await fetch("https://netarz.ir/api/ai/v1/audio/music", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NETARZ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openrouter/google/lyria-3-clip-preview",
    prompt: "قطعهٔ آرام لو‌فای با پیانو، تمپوی کند، حال‌وهوای امیدوار، بدون کلام",
  }),
}).then((r) => r.json());

await writeFile("clip.mp3", Buffer.from(res.data[0].b64_json, "base64"));

cURL

curl https://netarz.ir/api/ai/v1/audio/music \
  -H "Authorization: Bearer $NETARZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/google/lyria-3-pro-preview",
    "prompt": "آهنگ پاپ شاد با گیتار آکوستیک و ریتم تند، متن ترانه دربارهٔ سفر جاده‌ای"
  }' | jq -r '.data[0].b64_json' | base64 -d > song.mp3

پاسخ

{
  "id": "req_8f1c…",
  "object": "music.generation",
  "created": 1790108014,
  "model": "openrouter/google/lyria-3-clip-preview",
  "text": "<instrumental>",
  "data": [
    { "b64_json": "SUQzAwAAAAAvMkdFT0IA…", "format": "mp3", "bytes": 744608 }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 4, "total_tokens": 22 }
}

پارامترها

پارامتر	توضیح
`model` الزامی	`openrouter/google/lyria-3-clip-preview` برای کلیپ تا ۳۰ ثانیه، یا `openrouter/google/lyria-3-pro-preview` برای آهنگ کامل.
`prompt` الزامی	توصیف قطعه، تا ۴۰۰۰ کاراکتر: سبک، سازها، تمپو و حال‌وهوا. اگر متن ترانه بدهید، خوانده می‌شود.
`temperature`	میزان آزادی مدل در برداشت از توصیف شما. صفر تا ۱.
`seed`	با seed ثابت و همان توصیف، قطعه‌ای نزدیک به قبلی می‌گیرید.
`messages`	اگر به‌جای `prompt` بفرستید، همان شکل پیام‌های Chat Completions پذیرفته می‌شود — برای وقتی که تصویری را هم به‌عنوان الهام ضمیمه می‌کنید.

فیلدهای پاسخ

data[0].b64_json — خود فایل صوتی در قالب base64.
data[0].format — قالب فایل؛ در حال حاضر همیشه mp3.
text — یادداشت کوتاه خود مدل دربارهٔ قطعه (مثلاً <instrumental>). متنی برای نمایش به کاربر نیست.

قیمت‌گذاری

موسیقی به‌ازای هر قطعه حساب می‌شود، نه به‌ازای توکن: طول توصیف شما در مبلغ اثری ندارد و یک کلیپ سی‌ثانیه‌ای همیشه یک قیمت دارد. نرخ دقیق هر مدل زیر کلید per_request در فهرست قیمت‌ها آمده است.

درخواستی که به هر دلیل فایل صوتی برنگرداند، هزینه‌ای ندارد.
ساخت یک کلیپ حدود ده ثانیه و یک آهنگ کامل تا حدود یک دقیقه طول می‌کشد؛ در کلاینت خود timeout را دست‌کم روی ۱۸۰ ثانیه بگذارید.

نکات

فایل را همان‌جا ذخیره کنید؛ درگاه نسخه‌ای از قطعه نگه نمی‌دارد.
سبک، سازها، تمپو و حس قطعه را بنویسید. هرچه توصیف مشخص‌تر باشد، نتیجه نزدیک‌تر است.
برای قطعهٔ بی‌کلام، «بدون کلام» را هم در توصیف بیاورید.
حق استفادهٔ تجاری از خروجی را با شرایط خود گوگل بسنجید؛ ما قراردادی جدا از آن نداریم.

ساخت موسیقی

درخواست

پارامترها

فیلدهای پاسخ

قیمت‌گذاری

نکات