Music API؛ تولید موسیقی از روی توصیف با کار پسزمینه و کلید API
تولید موسیقی زمان میبرد، پس مسیر POST /v1/music/generations در وان ای آی (1ai) همیشه به صورت کار پسزمینه اجرا میشود: پاسخ 202 با یک شناسهی job_ میگیرید، وضعیت را میپرسید و بعد فایل را برمیدارید. اعتبار پیش از اجرا رزرو میشود و اگر کار شکست بخورد یا لغو شود، برمیگردد. این کارها و فایلهایشان در استودیو و گالری حساب شما دیده نمیشوند. روال کار همان است که در Video API میبینید.
چرا با 1ai
کار پسزمینه
درخواست فوراً با 202 و یک شناسه جواب میگیرد؛ لازم نیست اتصال را باز نگه دارید.
توصیف و متن ترانه
سبک و حالوهوای قطعه را در prompt بنویسید و متن ترانه را اگر دارید در lyrics بگذارید.
شکست و لغو بدون هزینه
اعتبار پیش از اجرا رزرو میشود. اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمیگردد.
در چند قدم
- ۱
کلید API بسازید
از بخش توسعهدهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.
- ۲
کار را بسازید
مدل و توصیف را به https://1ai.ir/v1/music/generations بفرستید و id را از پاسخ 202 بردارید.
- ۳
وضعیت را بپرسید
GET /v1/music/generations/{id} را با فاصله صدا بزنید تا status برابر completed یا failed شود.
- ۴
فایل را بردارید
مسیر content به یک لینک امضاشده هدایت میکند؛ در curl پرچم -L را بگذارید.
مدلهای موسیقی در API
همهی مدلهانمونه درخواست با curl
curl https://1ai.ir/v1/music/generations \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/lyria-3-clip",
"prompt": "Short calm santoor melody, instrumental"
}'پاسخ 202 همان شیء کار است:
{
"id": "job_…",
"object": "music",
"model": "google/lyria-3-clip",
"status": "queued",
"progress": 0,
"created_at": 1793923200,
"completed_at": null,
"prompt": "Short calm santoor melody, instrumental",
"estimated_credits": …,
"credits": …,
"output": null,
"error": null
}شناسهی مدل را از فهرست همین صفحه بردارید.
وضعیت، دریافت فایل، لغو
# Status
curl https://1ai.ir/v1/music/generations/job_... -H "Authorization: Bearer $ONEAI_API_KEY"
# Download when completed (follows the redirect)
curl -L -o result.mp3 https://1ai.ir/v1/music/generations/job_.../content -H "Authorization: Bearer $ONEAI_API_KEY"
# Cancel a running job, or delete a finished job's files
curl -X DELETE https://1ai.ir/v1/music/generations/job_... -H "Authorization: Bearer $ONEAI_API_KEY"نوع واقعی فایل در output.mime میآید.
status | معنی |
|---|---|
queued | در صف |
in_progress | در حال اجرا |
completed | تمام شده؛ output پر است و فایل آماده است |
failed | شکست خورده؛ علت در error است |
cancelled | لغو شده |
- دریافت فایل به یک لینک امضاشده هدایت میکند (302) که یک ساعت اعتبار دارد؛ برای لینک تازه همین مسیر را دوباره صدا بزنید.
DELETEکار در حال اجرا را لغو میکند و اعتبار رزروشده را برمیگرداند. روی کار تمامشده فایلها را حذف میکند و شیء کار باoutput: nullمیماند.
نمونه کامل با Python
# pip install requests
import os, time, requests
API = "https://1ai.ir/v1/music/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"}
job = requests.post(API, headers=HEADERS, json={
"model": "google/lyria-3-clip",
"prompt": "Short calm santoor melody, instrumental",
}, timeout=120).json()
while job["status"] in ("queued", "in_progress"):
time.sleep(10)
job = requests.get(f"{API}/{job['id']}", headers=HEADERS, timeout=60).json()
if job["status"] != "completed":
raise SystemExit(job["error"])
res = requests.get(f"{API}/{job['id']}/content", headers=HEADERS, timeout=300)
open("result.mp3", "wb").write(res.content)فیلدهای درخواست
بدنه JSON است.
| فیلد | نوع | توضیح |
|---|---|---|
model | رشته | شناسهی مدل موسیقی |
prompt | رشته | توصیف قطعه: سبک، ساز و حالوهوا |
lyrics | رشته، اختیاری | متن ترانه |
seconds | عدد، اختیاری | طول قطعه به ثانیه |
خطاها
| کد | معنی |
|---|---|
402 insufficient_credits | اعتبار کافی نیست |
400 model_kind_mismatch | این مدل برای این مسیر نیست |
404 job_not_found | کاری با این شناسه برای این حساب وجود ندارد |
409 job_not_ready | کار هنوز تمام نشده و فایلی ندارد |
404 content_not_found | فایل این کار حذف شده است |
اگر کاری شکست بخورد، علت در error.code میآید: media_input_refused، media_copyright_refused، provider_timeout، output_invalid، output_download_failed یا job_failed.
سوالات متداول
هزینهی موسیقی چطور حساب میشود؟
قیمت هر مدل در صفحهی همان مدل است. پیش از اجرا اعتبار رزرو میشود؛ تخمین آن در estimated_credits و مبلغ نهایی در credits میآید.
اگر کار شکست بخورد اعتبارم کم میشود؟
خیر. اگر کار شکست بخورد یا پیش از پایان لغو شود، اعتبار رزروشده برمیگردد. حذف فایلهای کاری که تمام شده است، هزینهی آن را برنمیگرداند.
لینک فایل چقدر اعتبار دارد؟
یک ساعت. برای لینک تازه دوباره GET /v1/music/generations/{id}/content را صدا بزنید. کتابخانههایی که هدایت را دنبال میکنند فایل را مستقیم میگیرند.
کارهای API در استودیو یا گالری من دیده میشوند؟
خیر. کارهای API و فایلهایشان فقط از همین مسیرها در دسترساند و در استودیو و گالری حساب شما نمیآیند.
مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژهای را که با کتابخانهی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدلها و مدیریت خطا.

کلید API در 1ai: امنیت، محدودیتها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدلهای مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
صفحههای مرتبط
همهی امکاناتVideo API
توصیف یا تصویر مرجع را بفرستید، شناسهی کار را بگیرید و وقتی کار تمام شد فایل ویدیو را بردارید. همگامسازی لب هم با یک عکس یا ویدیو و یک فایل صوتی به همین روش کار میکند.
OpenAI SDK
کتابخانهی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
Music API؛ تولید موسیقی از روی توصیف با کار پسزمینه و کلید API
توصیف قطعه و در صورت نیاز متن ترانه را بفرستید، شناسهی کار را بگیرید و وقتی کار تمام شد فایل صوتی را بردارید.
ساخت کلید API