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

Suno صوت إلى عبارة تحقق

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

عرض Markdown
01

نظرة عامة

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

البدء السريع

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

نقطة النهاية

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

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

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

03

مخطط الطلب

نص JSON

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

جسم الطلب5 حقل
callback_urlstring
اختياري

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

languagestring
اختياري

رمز اللغة.

القيم المسموح بها: en, zh, es, fr, pt, de, ja, ko, hi, ru
vocal_end_secondsinteger
مطلوب

وقت الانتهاء (بالثواني) لمقطع الصوت الصوتي المصدر. يجب أن يكون أكبر من vocal_start_seconds.

vocal_start_secondsinteger
مطلوب

وقت البداية (بالثواني) للمقطع الصوتي للمصدر.

voice_urlstring
مطلوب

رابط URL تسجيل الصوت المصدر.

04

إنشاء قبول

HTTP 202

POST /api/v1/suno/voice_to_validation_phrase

مخطط الاستجابة
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/voice_to_validation_phrase/: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
    },
    "id": {
      "type": "string"
    },
    "provider_status": {
      "enum": [
        "wait_processing",
        "processing_validate"
      ],
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "validation_phrase": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "provider_status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

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

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "provider_status": "processing_validate",
  "status": "processing"
}
06

اكتمل الاستطلاع

HTTP 200

GET /api/v1/suno/voice_to_validation_phrase/: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
    },
    "id": {
      "type": "string"
    },
    "provider_status": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "validation_phrase": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "provider_status",
    "validation_phrase",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

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

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "provider_status": "wait_validating",
  "status": "completed",
  "validation_phrase": "Harmonies fill the air with joyful melodies tonight."
}
07

فشل الاستطلاع

HTTP 200

GET /api/v1/suno/voice_to_validation_phrase/: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": {
    "id": {
      "type": "string"
    },
    "provider_status": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "validation_phrase": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "provider_status",
    "validation_phrase"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

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

JSON 
{
  "id": "tsk_reference_demo",
  "provider_status": "wait_validating",
  "status": "completed",
  "validation_phrase": "Harmonies fill the air with joyful melodies tonight."
}
09

استدعاء العميل: فشل

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"
}
10

الأخطاء

HTTP 401

POST /api/v1/suno/voice_to_validation_phrase

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

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

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

الأخطاء

HTTP 401

GET /api/v1/suno/voice_to_validation_phrase/:id

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

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

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

الأخطاء

HTTP 400

POST /api/v1/suno/voice_to_validation_phrase

مخطط الاستجابة
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": {
    "voice_url": [
      "is required"
    ]
  }
}
13

الأخطاء

HTTP 402

POST /api/v1/suno/voice_to_validation_phrase

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

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

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

الأخطاء

HTTP 429

POST /api/v1/suno/voice_to_validation_phrase

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

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

JSON 
{
  "error": "API key credit limit exceeded"
}
15

الأخطاء

HTTP 409

POST /api/v1/suno/voice_to_validation_phrase

مخطط الاستجابة
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"
}
16

الأخطاء

HTTP 429

POST /api/v1/suno/voice_to_validation_phrase

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

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

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

الأخطاء

HTTP 503

POST /api/v1/suno/voice_to_validation_phrase

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

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

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

الأخطاء

HTTP 504

POST /api/v1/suno/voice_to_validation_phrase

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

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

JSON 
{
  "error": "The request timed out"
}
19

الأخطاء

HTTP 404

GET /api/v1/suno/voice_to_validation_phrase/:id

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

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

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

نماذج الأكواد المولَّدة

استخدم 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.voice_to_validation_phrase.create(
  voice_url="https://file.runapi.ai/source-vocal.mp3",
  vocal_start_seconds=2,
  vocal_end_seconds=12,
  language="en"
)