مرجع API
Suno إضافة عينات
استخدم نقطة نهاية إضافة العينات لإنشاء مهمة Task غير متزامنة.
01
نظرة عامة
استخدم نقطة نهاية إضافة العينات مع نموذج مدعوم. استخدم معرّف Task المُعاد لاسترجاع حالته، أو وفّر callback_url لعمليات التسليم الموثقة أدناه.
البدء السريع
- أنشئ مفتاح API واضبطه كـ RUNAPI_API_KEY.
- اختر نموذجاً مدعوماً وأرسل طلب POST يطابق مخطط ذلك النموذج.
- احفظ معرّف المهمة المُعاد، ثم استطلع الحالة حتى تبلغ حالة نهائية أو تعالج عمليات الاستدعاء الموثقة أدناه.
نقطة النهاية
- عنوان URL الأساسي
https://runapi.ai- إصدار API
v1- المصادقة
Authorization: Bearer YOUR_API_TOKEN
02
النماذج المدعومة
افتح صفحة النموذج للاطلاع على التسعير الحالي وحدود المعدل وتفاصيل الاستخدام التجاري.
03
نص JSONمخطط الطلب
تعتمد الحقول والقيم المسموح بها على النموذج المحدد. عند التوفير، يستقبل callback_url عمليات تسليم المهمة الموثّقة أدناه.
suno-v46 حقل
audio_urlstring
مطلوب
عنوان URL للملف الصوتي المراد أخذ عينات منه.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
end_secondsnumber
مطلوب
نهاية نطاق العينة بالثواني؛ يجب أن تتجاوز start_seconds.
حد:0
modelstring
مطلوب
معرّف النموذج.
promptstring
اختياري
وصف اختياري للعينة المراد إضافتها.
start_secondsnumber
مطلوب
بداية نطاق العينة بالثواني.
حد:0
suno-v4.56 حقل
audio_urlstring
مطلوب
عنوان URL للملف الصوتي المراد أخذ عينات منه.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
end_secondsnumber
مطلوب
نهاية نطاق العينة بالثواني؛ يجب أن تتجاوز start_seconds.
حد:0
modelstring
مطلوب
معرّف النموذج.
promptstring
اختياري
وصف اختياري للعينة المراد إضافتها.
start_secondsnumber
مطلوب
بداية نطاق العينة بالثواني.
حد:0
suno-v4.5-plus6 حقل
audio_urlstring
مطلوب
عنوان URL للملف الصوتي المراد أخذ عينات منه.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
end_secondsnumber
مطلوب
نهاية نطاق العينة بالثواني؛ يجب أن تتجاوز start_seconds.
حد:0
modelstring
مطلوب
معرّف النموذج.
promptstring
اختياري
وصف اختياري للعينة المراد إضافتها.
start_secondsnumber
مطلوب
بداية نطاق العينة بالثواني.
حد:0
suno-v56 حقل
audio_urlstring
مطلوب
عنوان URL للملف الصوتي المراد أخذ عينات منه.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
end_secondsnumber
مطلوب
نهاية نطاق العينة بالثواني؛ يجب أن تتجاوز start_seconds.
حد:0
modelstring
مطلوب
معرّف النموذج.
promptstring
اختياري
وصف اختياري للعينة المراد إضافتها.
start_secondsnumber
مطلوب
بداية نطاق العينة بالثواني.
حد:0
suno-v5.56 حقل
audio_urlstring
مطلوب
عنوان URL للملف الصوتي المراد أخذ عينات منه.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
end_secondsnumber
مطلوب
نهاية نطاق العينة بالثواني؛ يجب أن تتجاوز start_seconds.
حد:0
modelstring
مطلوب
معرّف النموذج.
promptstring
اختياري
وصف اختياري للعينة المراد إضافتها.
start_secondsnumber
مطلوب
بداية نطاق العينة بالثواني.
حد:0
04
HTTP 202إنشاء قبول
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200الاستطلاع قيد المعالجة
GET /api/v1/suno/add_samples/:id
مخطط الاستجابة
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration": {
"type": "number"
},
"id": {
"type": "string"
},
"image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"lyrics": {
"type": "string"
},
"model_name": {
"type": "string"
},
"stream_audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"generation_stage": {
"enum": [
"text_generated",
"first_audio_ready"
],
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"generation_stage": "text_generated",
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200اكتمل الاستطلاع
GET /api/v1/suno/add_samples/:id
مخطط الاستجابة
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration": {
"type": "number"
},
"id": {
"type": "string"
},
"image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"lyrics": {
"type": "string"
},
"model_name": {
"type": "string"
},
"stream_audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"generation_stage": {
"enum": [
"text_generated",
"first_audio_ready",
"all_audios_ready",
"failed"
],
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"audios",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"audios": [
{
"audio_url": "https://file.runapi.ai/reference-audio.mp3",
"id": "audio_reference"
}
],
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed"
}07
HTTP 200فشل الاستطلاع
GET /api/v1/suno/add_samples/:id
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200استدعاء العميل: قيد المعالجة
POST callback_url
مخطط الاستجابة
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration": {
"type": "number"
},
"id": {
"type": "string"
},
"image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"lyrics": {
"type": "string"
},
"model_name": {
"type": "string"
},
"stream_audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"generation_stage": {
"enum": [
"text_generated",
"first_audio_ready"
],
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"generation_stage": "text_generated",
"id": "tsk_reference_demo",
"status": "processing"
}09
HTTP 200استدعاء العميل: مكتمل
POST callback_url
مخطط الاستجابة
JSON
{
"properties": {
"audios": {
"items": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration": {
"type": "number"
},
"id": {
"type": "string"
},
"image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"lyrics": {
"type": "string"
},
"model_name": {
"type": "string"
},
"stream_audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"generation_stage": {
"enum": [
"text_generated",
"first_audio_ready",
"all_audios_ready",
"failed"
],
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"audios"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"audios": [
{
"audio_url": "https://file.runapi.ai/reference-audio.mp3",
"id": "audio_reference"
}
],
"id": "tsk_reference_demo",
"status": "completed"
}10
HTTP 200استدعاء العميل: فشل
POST callback_url
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}11
HTTP 401الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Authentication required"
}12
HTTP 401الأخطاء
GET /api/v1/suno/add_samples/:id
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Authentication required"
}13
HTTP 400الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "ملخص التحقق القابل للقراءة البشرية.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "رسائل التحقق مفتاحها حقل الطلب العام، مع مصفوفة من السلاسل القابلة للقراءة البشرية لكل حقل.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}مثال على الاستجابة
JSON
{
"error": "model must be one of: suno-v4, suno-v4.5, suno-v4.5-plus, suno-v5, suno-v5.5"
}14
HTTP 402الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Insufficient balance"
}15
HTTP 429الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "API key credit limit exceeded"
}16
HTTP 409الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "The request uses features that are not supported for the selected model"
}17
HTTP 429الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Rate limit reached. Please retry later."
}18
HTTP 503الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Service under maintenance, please try again later"
}19
HTTP 504الأخطاء
POST /api/v1/suno/add_samples
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "The request timed out"
}20
HTTP 404الأخطاء
GET /api/v1/suno/add_samples/:id
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}21
نماذج الأكواد المولَّدة
استخدم cURL مباشرةً، أو ثبّت SDK للغة البرمجة التي تستخدمها. كل نموذج يُرسل الطلب الذي تم التحقق من صحته كما هو موضح في هذا المرجع.
التثبيت
Shell
pip install runapi-suno
PYTHON
import os
from runapi.suno import SunoClient
client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.add_samples.create(
model="suno-v5",
audio_url="https://cdn.runapi.ai/public/samples/music.mp3",
prompt="Add a crisp handclap sample to the chorus.",
start_seconds=10,
end_seconds=30
)