راهنمای اتصال به API

Music API؛ تولید موسیقی از روی توصیف با کار پس‌زمینه و کلید API

تولید موسیقی زمان می‌برد، پس مسیر POST /v1/music/generations در وان ای آی (1ai) همیشه به صورت کار پس‌زمینه اجرا می‌شود: پاسخ 202 با یک شناسه‌ی job_ می‌گیرید، وضعیت را می‌پرسید و بعد فایل را برمی‌دارید. اعتبار پیش از اجرا رزرو می‌شود و اگر کار شکست بخورد یا لغو شود، برمی‌گردد. این کارها و فایل‌هایشان در استودیو و گالری حساب شما دیده نمی‌شوند. روال کار همان است که در Video API می‌بینید.

چرا با 1ai

کار پس‌زمینه

درخواست فوراً با 202 و یک شناسه جواب می‌گیرد؛ لازم نیست اتصال را باز نگه دارید.

توصیف و متن ترانه

سبک و حال‌وهوای قطعه را در prompt بنویسید و متن ترانه را اگر دارید در lyrics بگذارید.

شکست و لغو بدون هزینه

اعتبار پیش از اجرا رزرو می‌شود. اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمی‌گردد.

در چند قدم

  1. ۱

    کلید API بسازید

    از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.

  2. ۲

    کار را بسازید

    مدل و توصیف را به https://1ai.ir/v1/music/generations بفرستید و id را از پاسخ 202 بردارید.

  3. ۳

    وضعیت را بپرسید

    GET /v1/music/generations/{id} را با فاصله صدا بزنید تا status برابر completed یا failed شود.

  4. ۴

    فایل را بردارید

    مسیر content به یک لینک امضاشده هدایت می‌کند؛ در curl پرچم -L را بگذارید.

مدل‌های موسیقی در API

همه‌ی مدل‌ها

Lyria 3 Clip

گوگل
موسیقی

قطعه‌ی موسیقی ۳۰ ثانیه‌ای از روی توصیف

۶ اعتبار / هر آهنگ
API

Lyria 3 Pro

گوگل
موسیقی

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

۱۲ اعتبار / هر آهنگ
API

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

bash
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 همان شیء کار است:

json
{
  "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
}

شناسه‌ی مدل را از فهرست همین صفحه بردارید.

وضعیت، دریافت فایل، لغو

bash
# 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

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
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

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

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

۴ دقیقه مطالعه
همه‌ی امکانات

Video API

توصیف یا تصویر مرجع را بفرستید، شناسه‌ی کار را بگیرید و وقتی کار تمام شد فایل ویدیو را بردارید. همگام‌سازی لب هم با یک عکس یا ویدیو و یک فایل صوتی به همین روش کار می‌کند.

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

Music API؛ تولید موسیقی از روی توصیف با کار پس‌زمینه و کلید API

توصیف قطعه و در صورت نیاز متن ترانه را بفرستید، شناسه‌ی کار را بگیرید و وقتی کار تمام شد فایل صوتی را بردارید.

ساخت کلید API