API ساخت موسیقی با هوش مصنوعی: Lyria 3، کد Python و قیمت هر قطعه

اگر برای ویدیوهای سایتت، اینتروی پادکست یا صدای پس‌زمینهٔ یک اپ موسیقی لازم داری، دو راه رایج داری: از کتابخانه‌های موسیقی آماده بخری، یا قطعه را با هوش مصنوعی بسازی. این مقاله دربارهٔ راه دوم است: API ساخت موسیقی با هوش مصنوعی که داخل محصول خودت صدایش می‌زنی، نه سایتی که دستی در آن تایپ کنی. در یوتاپن مسیر POST /v1/audio/music با همان کلید sk-up- و همان کیف پول تومانی که برای مدل‌های متنی داری، از دو مدل Lyria 3 گوگل قطعه می‌سازد و لینک فایل MP3 را برمی‌گرداند.

پایین‌تر می‌بینی کدام مدل برای چه کاری است، درخواست دقیقاً چه شکلی دارد، هزینه چطور حساب می‌شود و دربارهٔ کلام فارسی و حق استفاده از قطعه چه چیزی را باید خودت بررسی کنی.

چرا API موسیقی و نه سایت ساخت آهنگ

سایت‌های ساخت آهنگ برای یک‌بار ساختن خوب‌اند. ولی اگر کارت تکرارشونده است، API انتخاب منطقی‌تری است. چند نمونه:

• ویدیوساز یا اپ ادیت ویدیو که برای هر ویدیوی کاربر یک موسیقی پس‌زمینهٔ تازه می‌خواهد.
• سایت پادکست یا کتاب صوتی که برای هر قسمت یک اینترو یا پل کوتاه لازم دارد.
• تیم تولید محتوا که برای استوری‌ها و تیزرهای تبلیغاتی جینگل‌های مختلف می‌سازد و نمی‌خواهد هر بار یک قطعهٔ آماده را دوباره استفاده کند.
• بازی یا اپ آرامش و تمرکز که موسیقی بی‌کلام با حال‌وهوای مشخص لازم دارد.

خرید مستقیم از گوگل برای کاربر ایرانی همان مشکل همیشگی را دارد: حساب و پرداخت ارزی و کارت بین‌المللی. ریسک کارت مجازی و حساب واسطه را در راهنمای دسترسی به API مدل‌ها از ایران توضیح داده‌ایم. در یوتاپن با موبایل ایرانی ثبت‌نام می‌کنی، کیف پول را با زیبال به تومان شارژ می‌کنی و آدرس api.uttapen.ir داخل ایران است. مسیر بین‌المللی درخواست را زیرساخت ما در خارج از ایران مدیریت می‌کند.

دو مدل Lyria 3: قطعهٔ کامل یا کلیپ کوتاه

کاتالوگ ما امروز دو مدل موسیقی دارد که هر دو را گوگل ساخته و هر دو نسخهٔ Preview هستند. یعنی سازنده ممکن است رفتار یا در دسترس بودنشان را تغییر دهد. ستون «کاربرد» از توضیح خود سازنده و از جدول انتخاب خودکار ما آمده، نه از مقایسهٔ کیفیت.

قاعدهٔ ساده برای انتخاب:

• اینترو، جینگل، استوری و تیزر کوتاه‌اند و نسخهٔ Clip برایشان ساخته شده.
• موسیقی پس‌زمینهٔ یک ویدیوی چنددقیقه‌ای، قطعهٔ کامل برای پادکست یا آهنگ کار نسخهٔ Pro است. مستندات و کاتالوگ عدد دقیقی برای حداکثر طول قطعهٔ Pro نمی‌دهند، پس مدت تقریبی را در پرامپت بنویس و نتیجه را بسنج.
• اگر مطمئن نیستی، uttapen/auto-music را بفرست. انتخاب با یک قاعدهٔ ثابت و بدون هزینهٔ اضافه انجام می‌شود: اگر در پرامپت حرف از «کوتاه»، «جینگل»، «اینترو» یا «۳۰ ثانیه» (یا short، jingle، intro) باشد، Clip را برمی‌دارد و در غیر این صورت Pro را. دلیل انتخاب در uttapen.auto پاسخ می‌آید. اگر خودت مدلی را نام ببری، همیشه همان اجرا می‌شود.

ساخت موسیقی با API در Python

این مسیر در SDK رسمی OpenAI وجود ندارد، پس با یک درخواست HTTP ساده صدایش می‌زنی. پاسخ همگام (synchronous) است: درخواست تا آماده شدن قطعه باز می‌ماند که معمولاً کمتر از یک دقیقه طول می‌کشد. برای همین timeout کلاینت را بلند بگذار:

import os
import httpx

r = httpx.post(
    "https://api.uttapen.ir/v1/audio/music",
    headers={"Authorization": f"Bearer {os.environ['UTTAPEN_API_KEY']}"},
    json={
        "model": "google/lyria-3-clip-preview",   # یا uttapen/auto-music
        "prompt": "upbeat jingle for a coffee shop ad, acoustic guitar and light percussion, 20 seconds",
    },
    timeout=420,
)
r.raise_for_status()

if r.status_code == 202:
    job = r.json()                      # ساخت هنوز تمام نشده
    print("بعداً بگیر:", job["id"])
else:
    track = r.json()
    url = track["data"][0]["url"]        # لینک امضاشده، ۲۴ ساعت معتبر
    with open("jingle.mp3", "wb") as f:
        f.write(httpx.get(url, timeout=120).content)
    print("هزینه:", track["uttapen"]["cost_toman"], "تومان")

اگر ساخت از حدود شش دقیقه بیشتر طول بکشد، به‌جای قطعه پاسخ 202 با شیء کار می‌گیری؛ برای همین timeout نمونهٔ بالا کمی بیشتر از شش دقیقه است تا این پاسخ را از دست ندهی. ساخت در سرور ادامه پیدا می‌کند و نتیجه را بعداً با GET /v1/uttapen/media/{id} می‌خوانی. همین مسیر برای گرفتن لینک تازه بعد از منقضی شدن لینک قبلی هم کار می‌کند. شناسهٔ کار در هدر X-Uttapen-Media-Id هم می‌آید.

همان درخواست با curl

curl https://api.uttapen.ir/v1/audio/music \
  -H "Authorization: Bearer $UTTAPEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uttapen/auto-music",
    "prompt": "پیانوی آرام، عصر بارانی، بی‌کلام، حدود یک دقیقه",
    "seed": 42
  }'

پاسخ موفق این شکل را دارد:

{
  "created": 1791071431,
  "model": "google/lyria-3-pro-preview",
  "data": [{ "url": "https://api.uttapen.ir/v1/files/…/content?exp=…&sig=…", "mime_type": "audio/mpeg", "expires_at": "…" }],
  "uttapen": { "id": "01a1044a-…", "status": "completed", "cost_toman": "…", "hold_toman": "…" }
}

فیلدهایی که می‌توانی بفرستی:

فیلد image را دست‌کم نگیر. هر دو مدل Lyria 3 ورودی تصویر می‌پذیرند، پس می‌توانی مثلاً فریمی از ویدیویت یا عکس محصول را بفرستی تا حال‌وهوای قطعه از آن الهام بگیرد. فهرست کامل و جزئیات در مستندات ساخت موسیقی است.

پرامپت خوب برای موسیقی

مدل موسیقی با توصیف کار می‌کند، نه با نت. هرچه توصیفت مشخص‌تر باشد، نتیجه به چیزی که در ذهن داری نزدیک‌تر است. این چند جزء را در پرامپت بیاور:

1. سبک یا ژانر: لوفای، ارکسترال سینمایی، الکترونیک ملایم، آکوستیک.
2. سازها: پیانو، گیتار آکوستیک، سینث، زهی‌ها. اگر سنتور یا تار می‌خواهی، صریح بنویس و نتیجه را بسنج.
3. حال‌وهوا: آرام، پرانرژی، امیدوار، اسرارآمیز.
4. سرعت: آهسته، متوسط، تند. یا اگر عدد BPM را می‌دانی، همان را بنویس.
5. مدت تقریبی و کاربرد: «اینتروی ۱۵ ثانیه‌ای پادکست» یا «پس‌زمینهٔ ویدیوی دو دقیقه‌ای آموزشی».
6. بی‌کلام یا با خواننده: اگر کلام نمی‌خواهی، «بی‌کلام» یا instrumental را صریح بنویس.

پرامپت فارسی پذیرفته می‌شود و نمونهٔ curl بالا هم فارسی است. با این حال اگر نتیجه از درخواستت دور بود، همان توصیف را به انگلیسی هم امتحان کن و دو خروجی را کنار هم بگذار. با seed ثابت می‌توانی فقط یک جزء پرامپت را عوض کنی و اثرش را ببینی.

کلام فارسی و آهنگ با خواننده

API ما فیلد جداگانه‌ای برای متن ترانه ندارد و هر چیزی دربارهٔ کلام و خواننده را باید در همان prompt بنویسی. سازنده نسخهٔ Pro را برای «آهنگ کامل» معرفی کرده، ولی ما هیچ سندی نداریم که نشان دهد کلام فارسی، تلفظ درست و وزن شعر فارسی را خوب درمی‌آورد. کیفیت کلام فارسی تضمین‌شده نیست.

پیشنهاد عملی ما:

• برای بیشتر کاربردهای تجاری، مثل پس‌زمینهٔ ویدیو، اینترو و جینگل، قطعهٔ بی‌کلام بساز. ریسکش کمتر است و کمتر توجه شنونده را از محتوای اصلی می‌گیرد.
• اگر به گوینده یا پیام صوتی روی موسیقی نیاز داری، صدا را جدا با API تبدیل متن به صدای فارسی بساز و در تدوین روی قطعهٔ بی‌کلام بگذار. هم کنترل بیشتری داری و هم متن دقیقاً همان است که نوشته‌ای.
• اگر آهنگ با کلام فارسی می‌خواهی، اول با نسخهٔ Clip چند نمونهٔ کوتاه بساز و گوش کن، بعد سراغ قطعهٔ کامل برو.

قیمت هر قطعه چطور حساب می‌شود

قیمت موسیقی برخلاف مدل‌های متنی توکنی نیست و به‌ازای هر قطعه است. در این مقاله عدد تومانی نمی‌نویسیم، چون با نرخ ارز و قیمت سازنده عوض می‌شود. قیمت تقریبی امروز را روی صفحهٔ Lyria 3 Pro Preview و Lyria 3 Clip Preview ببین. روند پرداخت این است (جزئیاتش در مستندات رسانه):

1. پیش از ساخت، مبلغی بر اساس قیمت هر قطعه از کیف پول رزرو می‌شود. اگر موجودی کافی نباشد، خطای 402 می‌گیری و چیزی ساخته نمی‌شود.
2. بعد از ساخت، فقط هزینهٔ واقعی‌ای که سازندهٔ مدل گزارش می‌کند کم می‌شود و بقیهٔ رزرو برمی‌گردد.
3. ساخت ناموفق رایگان است. خطا، رد شدن به‌خاطر قوانین محتوا یا نرسیدن فایل، کل رزرو را آزاد می‌کند.

هزینهٔ نهایی در uttapen.cost_toman و هدر X-Uttapen-Cost-Toman می‌آید و موجودی بعد از آن در X-Uttapen-Balance-Toman. اشتراک ماهانه یا بستهٔ اعتباری نداریم و مدل موسیقی رایگان هم در کاتالوگ نیست. روش کلی پرداخت کیف پول، بدون اشتراک و هزینهٔ ثابت، در صفحهٔ قیمت‌ها آمده است.

حق استفاده از موسیقی ساخته‌شده

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

بند «استفادهٔ مجاز» همان شرایط هم می‌گوید سیاست‌های استفادهٔ سازندگان مدل را رعایت کنی. پس پیش از استفادهٔ تجاری، مثلاً در تبلیغ پولی یا انتشار روی پلتفرم‌های پخش، شرایط استفاده و سیاست‌های گوگل برای Lyria را خودت بخوان.

فایل، نگهداری و محدودیت‌ها

• خروجی فایل صوتی با mime_type برابر audio/mpeg (MP3) است.
• فایل‌ها روی سرور خودمان در ایران نگه داشته می‌شوند. لینک امضاشده ۲۴ ساعت بدون کلید باز می‌شود و خود فایل ۳۰ روز می‌ماند. اگر قطعه را بعداً لازم داری، در فضای خودت ذخیره‌اش کن.
• متن درخواست‌هایی که از API می‌فرستی ذخیره نمی‌شود.
• صدای ساخته‌شده شبیه افراد واقعی، محتوای جنسی، محتوای آسیب‌زا دربارهٔ کودکان و خشونت شدید ساخته نمی‌شود. چنین درخواستی با 400 content_policy_violation و پیام فارسی رد می‌شود و چیزی از کیف پول کم نمی‌شود.
• بیش از ۳ ساخت هم‌زمان خطای 429 با کد too_many_active_jobs می‌دهد و عبور از سقف ساخت در دقیقه rate_limit_exceeded. برای حجم بالا، درخواست‌ها را در صف بگذار و Retry-After را رعایت کن.

بدون نوشتن کد: استودیو

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

سؤال‌های رایج

Lyria API را از ایران چطور صدا بزنم؟

با یوتاپن، کلید sk-up- بساز و به https://api.uttapen.ir/v1/audio/music درخواست بفرست. شناسهٔ google/lyria-3-pro-preview برای قطعهٔ کامل و google/lyria-3-clip-preview برای کلیپ ۳۰ ثانیه‌ای است. نه VPN لازم است، نه کارت ارزی.

با SDK رسمی OpenAI می‌شود موسیقی ساخت؟

نه مستقیم، چون OpenAI مسیر ساخت موسیقی ندارد و SDK تابعی برای آن تعریف نکرده. با httpx، requests یا هر کلاینت HTTP دیگری صدایش بزن. برای متن، تصویر و گفتار همان SDK رسمی با base_url عوض‌شده کار می‌کند.

چند ثانیه موسیقی می‌شود ساخت؟

نسخهٔ Clip طبق توضیح سازنده کلیپ ۳۰ ثانیه‌ای می‌سازد. نسخهٔ Pro برای قطعهٔ کامل است، ولی عدد دقیقی برای حداکثر طول آن در مستندات نیامده. مدت تقریبی را در پرامپت بنویس و طول فایل خروجی را بررسی کن.

اگر ساخت شکست بخورد پولش کم می‌شود؟

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

موسیقی را برای ویدیو هم می‌شود ساخت؟

بله، این یکی از کاربردهای اصلی‌اش است. ویدیو را با API ساخت ویدیو یا ابزار خودت بساز، موسیقی بی‌کلام را با Lyria و در صورت نیاز صدای گوینده را با TTS، و در تدوین کنار هم بگذار. برای کاور یا تصویر شاخص هم API ساخت عکس را ببین. حساب نداری؟ حساب بساز و کلید API بگیر.