تخطَّ إلى المحتوى
مرجع API
مرجع API

Suno نص إلى موسيقى

استخدم نقطة نهاية تحويل النص إلى موسيقى لإنشاء مهمة غير متزامنة.

عرض Markdown
01

نظرة عامة

استخدم نقطة نهاية تحويل النص إلى موسيقى مع نموذج مدعوم. استخدم معرّف المهمة المُعاد لاسترداد حالتها، أو أدخل callback_url للتسليمات الموثقة أدناه.

البدء السريع

  1. أنشئ مفتاح API واضبطه كـ RUNAPI_API_KEY.
  2. اختر نموذجاً مدعوماً وأرسل طلب POST يطابق مخطط ذلك النموذج.
  3. احفظ معرّف المهمة المُعاد، ثم استطلع الحالة حتى تبلغ حالة نهائية أو تعالج عمليات الاستدعاء الموثقة أدناه.

نقطة النهاية

POST /api/v1/suno/text_to_music
عنوان URL الأساسي
https://runapi.ai
إصدار API
v1
المصادقة
Authorization: Bearer YOUR_API_TOKEN
02

النماذج المدعومة

افتح صفحة النموذج للاطلاع على التسعير الحالي وحدود المعدل وتفاصيل الاستخدام التجاري.

03

مخطط الطلب

نص JSON

تعتمد الحقول والقيم المسموح بها على النموذج المحدد. عند التوفير، يستقبل callback_url عمليات تسليم المهمة الموثّقة أدناه.

suno-v415 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1
suno-v4.515 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1
suno-v4.5-all15 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1
suno-v4.5-plus15 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1
suno-v515 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1
suno-v5.516 حقل
audio_weightnumber
اختياري

وزن الصوت (0-1).

نطاق: 0 - 1
callback_urlstring
اختياري

رابط Webhook لإشعارات غير متزامنة.

continue_atnumber
اختياري

الطابع الزمني بالثواني للاستمرار منه.

duration_secondsinteger
اختياري

المدة المطلوبة بالثواني؛ متاحة فقط للطلبات المخصصة في Suno V5.5.

نطاق: 10 - 360
lyricsstring
اختياري

كلمات الغناء الدقيقة.

حد: 5000
modelstring
مطلوب

معرّف النموذج.

negative_tagsstring
اختياري

الأساليب الواجب تجنبها.

persona_idstring
اختياري

معرّف الشخصية.

persona_typestring
اختياري

نوع الشخصية.

القيم المسموح بها: style, voice
promptstring
اختياري

موجز الأغنية للكلمات التلقائية.

حد: 5000
stylestring
اختياري

أسلوب الموسيقى.

حد: 1000
style_weightnumber
اختياري

وزن الالتزام بالأسلوب (0-1).

نطاق: 0 - 1
titlestring
اختياري

عنوان الموسيقى.

حد: 80
vocal_genderstring
اختياري

جنس الصوت الغنائي.

القيم المسموح بها: male, female
vocal_modestring
مطلوب

وضع توليد الصوت الغنائي.

القيم المسموح بها: auto_lyrics, exact_lyrics, instrumental
weirdness_constraintnumber
اختياري

قيد الغرابة (0-1).

نطاق: 0 - 1

القواعد الشرطية

تسري هذه المتطلبات عندما تتطابق جميع الشروط المدرجة.

  1. عندما vocal_mode = auto_lyrics
    مطلوب
    prompt
    غير مقبول
    lyrics, style, title, negative_tags, vocal_gender, duration_seconds
  2. عندما vocal_mode = exact_lyrics
    مطلوب
    lyrics, style, title
    غير مقبول
    prompt
  3. عندما vocal_mode = instrumental
    مطلوب
    style, title
    غير مقبول
    prompt, lyrics, vocal_gender
  4. عندما model = suno-v4
    مطلوب
    غير مقبول
    duration_seconds
  5. عندما model = suno-v4.5
    مطلوب
    غير مقبول
    duration_seconds
  6. عندما model = suno-v4.5-all
    مطلوب
    غير مقبول
    duration_seconds
  7. عندما model = suno-v4.5-plus
    مطلوب
    غير مقبول
    duration_seconds
  8. عندما model = suno-v5
    مطلوب
    غير مقبول
    duration_seconds
04

إنشاء قبول

HTTP 202

POST /api/v1/suno/text_to_music

مخطط الاستجابة
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/text_to_music/: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/text_to_music/: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/text_to_music/: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/text_to_music

مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Authentication required"
}
12

الأخطاء

HTTP 401

GET /api/v1/suno/text_to_music/:id

مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Authentication required"
}
13

الأخطاء

HTTP 400

POST /api/v1/suno/text_to_music

مخطط الاستجابة
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": "Validation failed",
  "errors": {
    "prompt": [
      "is required"
    ]
  }
}
14

الأخطاء

HTTP 402

POST /api/v1/suno/text_to_music

مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Insufficient balance"
}
15

الأخطاء

HTTP 429

POST /api/v1/suno/text_to_music

مخطط الاستجابة
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/text_to_music

مخطط الاستجابة
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/text_to_music

مخطط الاستجابة
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/text_to_music

مخطط الاستجابة
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/text_to_music

مخطط الاستجابة
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/text_to_music/: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.text_to_music.create(
  model="suno-v5",
  vocal_mode="auto_lyrics",
  prompt="An uplifting acoustic pop song about a rainy city night.",
  persona_id="persona_reference",
  persona_type="style"
)