Azure مرجع واجهة برمجة تطبيقات REST للصور والصوت OpenAI (2024-10-21)

توثق هذه المقالة إنشاء الصور وعمليات واجهة برمجة تطبيقات REST لمستوى بيانات الصوت (الكلام) Azure OpenAI في 2024-10-21 إصدار GA. لإكمال الدردشة والتضمينات والإكمال وجميع العمليات الأخرى، راجع المرجع الرسمي Azure OpenAI REST API.

مواصفات واجهة برمجة التطبيقات

إدارة وتفاعل نماذج وموارد Azure OpenAI مقسمة عبر ثلاثة أسطح رئيسية لواجهات برمجة التطبيقات:

  • وحدة التحكم
  • مستوى البيانات - التأليف
  • مستوى البيانات - الاستدلال

كل سطح/مواصفة API تحتوي على مجموعة مختلفة من قدرات Azure OpenAI. لكل واجهة برمجة تطبيقات مجموعة فريدة من إصدارات المعاينة والمستقرة/المتاحة عموما (GA). إصدارات المعاينات حاليا تميل إلى اتباع وتيرة شهرية.

مهم

هناك الآن واجهة برمجة تطبيقات جديدة للاستدلالات التمهيدية. تعرف على المزيد في دليل دورة حياة واجهة برمجة التطبيقات الخاصة بنا.

API أحدث إصدار معاينة أحدث إصدار من GA المواصفات الوصف
وحدة التحكم 2025-07-01-preview 2025-06-01 ملفات المواصفات تستخدم واجهة برمجة تطبيقات مستوى التحكم في العمليات مثل إنشاء الموارد، ونشر النماذج، وغيرها من مهام إدارة الموارد على مستوى أعلى. كما يتحكم مستوى التحكم في ما يمكن فعله بقدرات مثل Azure Resource Manager وBicep وTerraform وAzure CLI.
مستوى البيانات v1 preview v1 ملفات المواصفات تتحكم واجهة برمجة التطبيقات في مستوى البيانات في عمليات الاستدلال والتأليف.

المصادقة

يوفر Azure OpenAI طريقتين للمصادقة. يمكنك استخدام مفاتيح API أو Microsoft Entra ID.

  • مصادقة مفتاح API: لهذا النوع من المصادقة، يجب أن تتضمن جميع طلبات API مفتاح API في api-key رأس HTTP. يوفر البدء السريع إرشادات حول كيفية إجراء المكالمات باستخدام هذا النوع من المصادقة.

  • Microsoft Entra ID المصادقة: يمكنك التحقق من استدعاء واجهة برمجة التطبيقات باستخدام رمز Microsoft Entra. يتم تضمين رموز المصادقة في الطلب كرأس Authorization رئيسي. يجب أن يسبق الرمز المقدم ب Bearer، على سبيل المثال Bearer YOUR_AUTH_TOKEN. يمكنك قراءة دليلنا التعليمي حول التحقق باستخدام Microsoft Entra ID.

إصدار REST API

يتم إصدار واجهات برمجة التطبيقات للخدمة باستخدام api-version معامل الاستعلام. جميع الإصدارات تتبع هيكل YYYY-MM-DD التاريخ. على سبيل المثال:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-06-01

استنتاج مستوى البيانات

تغطي بقية هذه المقالة عمليات الصور والصوت في إصدار GA لمواصفات استدلال مستوى بيانات OpenAI Azure، 2024-10-21.

للحصول على معاينة الصور وعمليات الصوت، راجع معاينة صورة ومرجع واجهة برمجة تطبيقات REST للصوت.

النسخ - إنشاء

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

يقوم بنسخ الصوت إلى لغة الإدخال.

معلمات URI

Name In مطلوبة النوع الوصف
نقطه النهايه مسار ‏‏نعم‬ string
عنوان URL		 دعم Azure نقاط نهاية OpenAI (البروتوكول واسم المضيف، على سبيل المثال: https://aoairesource.openai.azure.com. استبدل "aoairesource" باسم مورد Azure OpenAI الخاص بك). https://{your-resource-name}.openai.azure.com
معرف التوزيع مسار ‏‏نعم‬ string معرف النشر لنموذج تحويل الكلام إلى نص.

للحصول على معلومات حول النماذج المدعومة، راجع [/azure/ai-foundry/openai/concepts/models#audio-models].
إصدار API استعلام ‏‏نعم‬ string إصدار API

رأس الطلب

Name مطلوبة النوع الوصف
مفتاح واجهة برمجة التطبيقات صحيح string قدم مفتاح API Azure OpenAI هنا

هيئة الطلب

نوع المحتوى: متعدد الأجزاء/بيانات الشكل

Name النوع الوصف مطلوبة افتراضي
ملف string ملف الصوت يجب نسخه. ‏‏نعم‬
الموضوع string نص اختياري لتوجيه أسلوب النموذج أو استمرار مقطع صوتي سابق. يجب أن يتطابق الموضوع مع لغة الصوت. لا
response_format تنسيق الاستجابة الصوتية يحدد تنسيق المخرج. لا
درجة الحرارة number درجة حرارة العينة، بين 0 و1. القيم الأعلى مثل 0.8 ستجعل الناتج أكثر عشوائية، بينما القيم الأقل مثل 0.2 تجعله أكثر تركيزا وحتمية. إذا تم ضبطه على 0، سيستخدم النموذج احتمال لوغاريتيم لزيادة درجة الحرارة تلقائيا حتى تصل عتبات معينة. لا 1
اللغة string لغة الصوت المدخل. توفير لغة الإدخال بصيغة ISO-639-1 سيحسن الدقة والتأخير. لا

Responses

رمز الحالة: 200

الوصف: موافق

نوع المحتوى نوع الوصف
application/json audioResponse أو audioVerboseResponse
النص/البسيط string كان ينسخ النص بصيغة الإخراج (عندما response_format نصا أو VTT أو SRT).

الأمثلة

مثال

يحصل على النص المنقول والبيانات الوصفية المرتبطة به من بيانات الصوت المنطوقة المقدمة.

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

الردود: رمز الحالة: 200

{
  "body": {
    "text": "A structured object when requesting json or verbose_json"
  }
}

مثال

يحصل على النص المنقول والبيانات الوصفية المرتبطة به من بيانات الصوت المنطوقة المقدمة.

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

الردود: رمز الحالة: 200

{
  "type": "string",
  "example": "plain text when requesting text, srt, or vtt"
}

الترجمات - إنشاء

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-10-21

يقوم بنسخ وترجمة الصوت المدخل إلى النص الإنجليزي.

معلمات URI

Name In مطلوبة النوع الوصف
نقطه النهايه مسار ‏‏نعم‬ string
عنوان URL		 دعم Azure نقاط نهاية OpenAI (البروتوكول واسم المضيف، على سبيل المثال: https://aoairesource.openai.azure.com. استبدل "aoairesource" باسم مورد Azure OpenAI الخاص بك). https://{your-resource-name}.openai.azure.com
معرف التوزيع مسار ‏‏نعم‬ string معرف النشر لنموذج النسخ الذي تم نشره.

للحصول على معلومات حول النماذج المدعومة، راجع [/azure/ai-foundry/openai/concepts/models#audio-models].
إصدار API استعلام ‏‏نعم‬ string إصدار API

رأس الطلب

Name مطلوبة النوع الوصف
مفتاح واجهة برمجة التطبيقات صحيح string قدم مفتاح API Azure OpenAI هنا

هيئة الطلب

نوع المحتوى: متعدد الأجزاء/بيانات الشكل

Name النوع الوصف مطلوبة افتراضي
ملف string ملف الصوت للترجمة. ‏‏نعم‬
الموضوع string نص اختياري لتوجيه أسلوب النموذج أو استمرار مقطع صوتي سابق. يجب أن يكون الموضوع باللغة الإنجليزية. لا
response_format تنسيق الاستجابة الصوتية يحدد تنسيق المخرج. لا
درجة الحرارة number درجة حرارة العينة، بين 0 و1. القيم الأعلى مثل 0.8 ستجعل الناتج أكثر عشوائية، بينما القيم الأقل مثل 0.2 تجعله أكثر تركيزا وحتمية. إذا تم ضبطه على 0، سيستخدم النموذج احتمال لوغاريتيم لزيادة درجة الحرارة تلقائيا حتى تصل عتبات معينة. لا 1

Responses

رمز الحالة: 200

الوصف: موافق

نوع المحتوى نوع الوصف
application/json audioResponse أو audioVerboseResponse
النص/البسيط string كان ينسخ النص بصيغة الإخراج (عندما response_format نصا أو VTT أو SRT).

الأمثلة

مثال

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-10-21

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

الردود: رمز الحالة: 200

{
  "body": {
    "text": "A structured object when requesting json or verbose_json"
  }
}

مثال

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-10-21

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

الردود: رمز الحالة: 200

{
  "type": "string",
  "example": "plain text when requesting text, srt, or vtt"
}

إنشاء الصور

POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2024-10-21

ينشئ دفعة من الصور من تعليق نصي على نشر نموذج dall-e معين

معلمات URI

Name In مطلوبة النوع الوصف
نقطه النهايه مسار ‏‏نعم‬ string
عنوان URL		 دعم Azure نقاط نهاية OpenAI (البروتوكول واسم المضيف، على سبيل المثال: https://aoairesource.openai.azure.com. استبدل "aoairesource" باسم مورد Azure OpenAI الخاص بك). https://{your-resource-name}.openai.azure.com
معرف التوزيع مسار ‏‏نعم‬ string معرف النشر لنموذج dall-e الذي تم نشره.
إصدار API استعلام ‏‏نعم‬ string إصدار API

رأس الطلب

Name مطلوبة النوع الوصف
مفتاح واجهة برمجة التطبيقات صحيح string قدم مفتاح API Azure OpenAI هنا

هيئة الطلب

نوع المحتوى: application/json

Name النوع الوصف مطلوبة افتراضي
الموضوع string وصف نصي للصورة أو الصور المطلوبة. الحد الأقصى للطول هو 4,000 حرف. ‏‏نعم‬
n integer عدد الصور التي يجب إنشاؤها. لا 1
الحجم حجم الصورة حجم الصور المولدة. لا 1024x1024
response_format imagesResponseFormat الصيغة التي تعاد بها الصور المولدة. لا عنوان URL
المستخدم string معرف فريد يمثل المستخدم النهائي، يمكن أن يساعد في مراقبة واكتشاف سوء الاستخدام. لا
الجودة imageQuality جودة الصورة التي سيتم إنشاؤها. لا قياسي
الأسلوب imageStyle أسلوب الصور المولدة. لا حيه

Responses

رمز الحالة: 200

الوصف: موافق

نوع المحتوى نوع الوصف
application/json إنشاءImagesResponse

رمز الحالة: افتراضي

الوصف: حدث خطأ.

نوع المحتوى نوع الوصف
application/json داليErrorResponse

الأمثلة

مثال

ينشئ صورا مع توجيه.

POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2024-10-21

{
 "prompt": "In the style of WordArt, Microsoft Clippy wearing a cowboy hat.",
 "n": 1,
 "style": "natural",
 "quality": "standard"
}

الردود: رمز الحالة: 200

{
  "body": {
    "created": 1698342300,
    "data": [
      {
        "revised_prompt": "A vivid, natural representation of Microsoft Clippy wearing a cowboy hat.",
        "prompt_filter_results": {
          "sexual": {
            "severity": "safe",
            "filtered": false
          },
          "violence": {
            "severity": "safe",
            "filtered": false
          },
          "hate": {
            "severity": "safe",
            "filtered": false
          },
          "self_harm": {
            "severity": "safe",
            "filtered": false
          },
          "profanity": {
            "detected": false,
            "filtered": false
          }
        },
        "url": "https://dalletipusw2.blob.core.windows.net/private/images/e5451cc6-b1ad-4747-bd46-b89a3a3b8bc3/generated_00.png?se=2023-10-27T17%3A45%3A09Z&...",
        "content_filter_results": {
          "sexual": {
            "severity": "safe",
            "filtered": false
          },
          "violence": {
            "severity": "safe",
            "filtered": false
          },
          "hate": {
            "severity": "safe",
            "filtered": false
          },
          "self_harm": {
            "severity": "safe",
            "filtered": false
          }
        }
      }
    ]
  }
}

المكونات

للحصول على تعريفات المخطط المستخدمة بواسطة الدردشة والإكمالات والتضمينات والعمليات النصية الأخرى، راجع مرجع واجهة برمجة تطبيقات REST Azure OpenAI. تدعم المخططات التالية عمليات الصور والصوت في هذه الصفحة.

innerErrorCode

رموز الخطأ لكائن الخطأ الداخلي.

الوصف: رموز خطأ لكائن الخطأ الداخلي.

النوع: السلسلة

الافتراضي:

اسم Enum: InnerErrorCode

قيم التعداد:

قيمة الوصف
نهجAI المسؤول الموضوع انتهك إحدى قواعد تصفية المحتوى.

داليErrorResponse

Name النوع الوصف مطلوبة افتراضي
خطأ داليError لا

داليError

Name النوع الوصف مطلوبة افتراضي
برام string لا
النوع string لا
inner_error dalleInnerError خطأ داخلي مع تفاصيل إضافية. لا

dalleInnerError

خطأ داخلي مع تفاصيل إضافية.

Name النوع الوصف مطلوبة افتراضي
الرمز innerErrorCode رموز الخطأ لكائن الخطأ الداخلي. لا
content_filter_results dalleFilterResults معلومات عن فئة تصفية المحتوى (الكراهية، الجنس، العنف، self_harm)، وإذا تم اكتشافها، بالإضافة إلى مستوى الشدة (very_low، منخفض، متوسط، عالي النطاق الذي يحدد شدة ومستوى خطر المحتوى الضار) وما إذا تم تصفيته أم لا. معلومات عن محتوى الجيلبريك والألفاظ النابية، وإذا تم اكتشافه، وإذا تم تصفيتها أم لا. ومعلومات عن قائمة حظر العملاء، إذا تم تصفيتها ومعرفها. لا
revised_prompt string المحفز الذي استخدم لإنشاء الصورة، إذا كان هناك أي تعديل على الطلب. لا

contentFilterSeverityResult

Name النوع الوصف مطلوبة افتراضي
مفلتر boolean ‏‏نعم‬
الشدة string لا

contentFilterDetectedResult

Name النوع الوصف مطلوبة افتراضي
مفلتر boolean ‏‏نعم‬
تم اكتشافه boolean لا

dalleFilterResults

معلومات عن فئة تصفية المحتوى (الكراهية، الجنس، العنف، self_harm)، وإذا تم اكتشافها، بالإضافة إلى مستوى الشدة (very_low، منخفض، متوسط، عالي النطاق الذي يحدد شدة ومستوى خطر المحتوى الضار) وما إذا تم تصفيته أم لا. معلومات عن محتوى الجيلبريك والألفاظ النابية، وإذا تم اكتشافه، وإذا تم تصفيتها أم لا. ومعلومات عن قائمة حظر العملاء، إذا تم تصفيتها ومعرفها.

Name النوع الوصف مطلوبة افتراضي
الجنس contentFilterSeverityResult لا
العنف contentFilterSeverityResult لا
الكراهية contentFilterSeverityResult لا
self_harm contentFilterSeverityResult لا
الألفاظ النابية contentFilterDetectedResult لا
الهروب من السجن contentFilterDetectedResult لا

الاستجابة الصوتية

استجابة الترجمة أو النسخ عندما response_format json

Name النوع الوصف مطلوبة افتراضي
النص string نص مترجم أو منقول. ‏‏نعم‬

audioVerboseResponse

استجابة الترجمة أو النسخ عندما response_format verbose_json

Name النوع الوصف مطلوبة افتراضي
النص string نص مترجم أو منقول. ‏‏نعم‬
المهمة string نوع من المهام الصوتية. لا
اللغة string اللغه. لا
المدة number مده. لا
المقاطع مصفوفة لا

تنسيق الاستجابة الصوتية

يحدد تنسيق المخرج.

الوصف: يحدد تنسيق المخرج.

النوع: السلسلة

الافتراضي:

قيم التعداد:

  • json
  • النص
  • الصربيه
  • verbose_json
  • vtt

imageQuality

جودة الصورة التي سيتم إنشاؤها.

الوصف: جودة الصورة التي سيتم إنشاؤها.

النوع: السلسلة

الافتراضي: قياسي

اسم Enum: الجودة

قيم التعداد:

قيمة الوصف
قياسي الجودة القياسية تخلق صورا بجودة قياسية.
هد جودة HD تخلق صورا بتفاصيل أدق وأكثر اتساقا عبر الصورة.

imagesResponseFormat

الصيغة التي تعاد بها الصور المولدة.

الوصف: الصيغة التي تعاد بها الصور المولدة.

النوع: السلسلة

الافتراضي: url

اسم Enum: ImagesResponseFormat

قيم التعداد:

قيمة الوصف
عنوان URL الرابط الذي يوفر وصولا مؤقتا لتحميل الصور المولدة.
b64_json يتم إرجاع الصور المولدة كسلسلة مشفرة base64.

حجم الصورة

حجم الصور المولدة.

الوصف: حجم الصور المولدة.

النوع: السلسلة

الافتراضي: 1024x1024

اسم إينوم: الحجم

قيم التعداد:

قيمة الوصف
1792x1024 الحجم المطلوب للصورة المولدة هو 1792x1024 بكسل.
1024x1792 الحجم المطلوب للصورة المولدة هو 1024x1792 بكسل.
1024x1024 الحجم المطلوب للصورة المولدة هو 1024x1024 بكسل.

imageStyle

أسلوب الصور المولدة.

الوصف: أسلوب الصور التي تم إنشاؤها.

النوع: السلسلة

الافتراضي: حي

اسم إينوم: الأسلوب

قيم التعداد:

قيمة الوصف
حيه يخلق Vivid صورا واقعية للغاية ودرامية.
الطبيعيه Natural يخلق صورا أكثر طبيعية وأقل واقعية مفرطة.

إنشاءImagesResponse

Name النوع الوصف مطلوبة افتراضي
تم إنشاؤه integer طابع يونكس الزمني عند إنشاء العملية. ‏‏نعم‬
البيانات مصفوفة بيانات نتيجة العملية، إذا نجحت ‏‏نعم‬

الخطوات التالية

تعرف على النماذج والضبط الدقيق مع واجهة برمجة تطبيقات REST. تعرف أكثر على النماذج الأساسية التي تشغل Azure OpenAI.

  • Last updated on