> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات التعرف على الصوت من OpenAI (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

تحويل الصوت إلى نص، **متوافق تمامًا مع `/v1/audio/transcriptions` من OpenAI**. أي SDK من OpenAI يحتاج فقط إلى توجيه `base_url` إلى `https://api.acedata.cloud`، واستبدال المفتاح برمز AceData الخاص بك لاستخدامه مباشرة. يدعم الاستجابة الكاملة العادية، كما يدعم التحويل التدريجي لـ `gpt-transcribe` عبر SSE.

* **عنوان الطلب**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (اسم مستعار `POST /openai/audio/transcriptions`)
* **المصادقة**: رأس الطلب `Authorization: Bearer {token}`
* **تنسيق الطلب**: `multipart/form-data`
* **الفوترة**: يتم احتساب الرسوم بناءً على مدة الصوت (انظر الجدول أدناه)، وأي مدة أقل من 1 ثانية يتم احتسابها كـ 1 ثانية.

## معلمات الطلب

| الحقل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `file` | ملف | نعم | ملف الصوت المراد تحويله، بحد أقصى 25 ميجابايت. يدعم `flac`، `mp3`، `mp4`، `mpeg`، `mpga`، `m4a`، `ogg`، `wav`، `webm`. |
| `model` | سلسلة | لا | `whisper-1` (افتراضي) أو `gpt-transcribe`، انظر الجدول أدناه للاختلافات في القدرات. |
| `language` | سلسلة | لا | لغة الصوت، رمز ISO-639-1 (مثل `zh`، `en`). ملؤها يمكن أن يحسن الدقة والسرعة؛ إذا تركت فارغة، سيتم التعرف عليها تلقائيًا. |
| `prompt` | سلسلة | لا | كلمات توجيهية، تستخدم لتوجيه أسلوب الكتابة، أو تقديم أسماء خاصة، مصطلحات لتحسين دقة التعرف. |
| `response_format` | سلسلة | لا | `whisper-1`: `json` (افتراضي)، `text`، `srt`، `verbose_json`، `vtt`؛ `gpt-transcribe`: فقط `json`، `text`. |
| `temperature` | رقم | لا | درجة حرارة العينة من 0 إلى 1، الافتراضي 0. |
| `timestamp_granularities[]` | مصفوفة | لا | دقة الطابع الزمني، `word` أو `segment`، يجب استخدامها مع `response_format=verbose_json`. |
| `languages[]` | مصفوفة | لا | لغات مرشحة (ISO-639-1)، **فقط `gpt-transcribe`**. متعارضة مع `language`، لا ترسلها معًا. |
| `keywords[]` | مصفوفة | لا | كلمات خاصة/مصطلحات توجيهية، **فقط `gpt-transcribe`**، يمكن أن تحسن بشكل كبير دقة التعرف على أسماء العلامات التجارية والأشخاص. |
| `stream` | منطقي | لا | عند تعيين `gpt-transcribe` إلى `true`، يتم إرجاع أحداث SSE التدريجية؛ `whisper-1` سيتجاهل هذه المعلمة ويعيد النتيجة الكاملة (متوافق مع سلوك OpenAI الرسمي). |

## أي نموذج تختار

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| السعر | \$0.0078 / دقيقة | **\$0.0059 / دقيقة** (أرخص) |
| دقة التعرف | جيدة | **أفضل**، خاصة في أسماء العلامات التجارية، والأسماء الخاصة |
| إخراج الترجمة ( `srt` / `vtt` ) | ✅ | ❌ |
| الطابع الزمني على مستوى الكلمة | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| إرجاع اللغة المكتشفة | يحتاج إلى `verbose_json` | إرجاع افتراضي |
| إرجاع التدفق التدريجي | ❌ (يتم تجاهل `stream`) | ✅ |

**تحتاج إلى ترجمة أو طابع زمني على مستوى الكلمة → `whisper-1`؛ باقي السيناريوهات يوصى بـ `gpt-transcribe`** (أكثر دقة وأرخص).

## مثال

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1
```

العودة:

```json theme={null}
{
  "text": "منصة Ace Data Cloud تختبر نقطة نهاية التعرف على الصوت. الثعلب البني السريع يقفز فوق الكلب الكسول."
}
```

يدعم الصوت باللغة الصينية أيضًا، دون الحاجة لتحديد اللغة:

```json theme={null}
{
  "text": "مرحبًا بكم في منصة AceData Cloud، نحن نختبر واجهة التعرف على الصوت، اليوم هو 31 يوليو."
}
```

### إنشاء ترجمة

قم بتعيين `response_format` إلى `srt` أو `vtt`، للحصول على ملف ترجمة قابل للاستخدام مباشرة:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=srt \
  -o subtitle.srt
```

محتوى العودة ( `Content-Type: text/plain` ):

```
1
00:00:00,000 --> 00:00:03,800
منصة Ace Data Cloud تختبر نقطة نهاية التعرف على الصوت.

2
00:00:03,800 --> 00:00:06,280
الثعلب البني السريع يقفز فوق الكلب الكسول.
```

### الطابع الزمني على مستوى الكلمة

عند الحاجة إلى وقت البدء والانتهاء لكل كلمة، استخدم `verbose_json` مع `timestamp_granularities[]=word`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=verbose_json \
  -F 'timestamp_granularities[]=word'
```

العودة:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "منصة Ace Data Cloud تختبر نقطة نهاية التعرف على الصوت. الثعلب البني السريع يقفز فوق الكلب الكسول.",
  "words": [
    {
      "word": "Ace",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "Data",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Cloud",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### التحويل التدريجي

يمكن لـ `gpt-transcribe` إرجاع `Content-Type: text/event-stream` عبر `stream=true`. ستقوم الخدمة بإرسال أحداث متوافقة مع OpenAI كما هي:
`transcript.text.delta` يحمل النص التدريجي، و `transcript.text.done` يحمل النص الكامل و `usage` ويشير إلى الانتهاء بشكل طبيعي.

```shell theme={null}
curl -N -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=gpt-transcribe \
  -F stream=true
```

مثال على تدفق الأحداث:

```text theme={null}
data: {"type":"transcript.text.delta","delta":"مرحبًا"}

data: {"type":"transcript.text.done","text":"مرحبًا بالعالم","usage":{"type":"tokens","input_tokens":14,"output_tokens":3,"total_tokens":17}}
```

استلام `transcript.text.done` فقط يشير إلى الانتهاء بشكل طبيعي. إذا فشل المعالجة بعد إنشاء التدفق، ستنتهي الاتصال بعد حدث `event: error`؛ إذا قام العميل بفصل الاتصال، سيتم إلغاء المعالجة الحالية، ولن تستمر في الخلفية. حتى إذا تم تمرير `stream=true`، فإن `whisper-1` سيظل يعيد استجابة عادية غير تدفقية.

### استخدام SDK الرسمي

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)
print(result.text)
```

## الأسعار

| النموذج | سعر المنصة |
| - | - |
| `whisper-1` | \$0.0078 / دقيقة |
| `gpt-transcribe` | \$0.0059 / دقيقة |

> يتم احتساب الرسوم بناءً على الطول الفعلي للصوت، وأي جزء أقل من 1 ثانية يتم احتسابه كـ 1 ثانية، وأقصى مدة لمرة واحدة هي 1 ساعة.

## ملاحظات

* الحد الأقصى لحجم الملف الواحد هو **25 ميغابايت**. إذا تجاوز ذلك، يرجى تقسيمه أو ضغطه (تقليل معدل البت عادة يكفي، حيث أن التعرف على الصوت لا يتطلب جودة صوت عالية).
* يدعم `gpt-transcribe` `stream=true` SSE؛ بينما سيتجاهل `whisper-1` `stream` ويعيد النتيجة الكاملة.
* المعلمات متوافقة مع OpenAI الرسمية `/v1/audio/transcriptions`، يمكن استخدام SDK الرسمي فقط بتغيير `base_url`.
* `include[]`، `chunking_strategy`، `known_speaker_names[]`، `known_speaker_references[]` هي نماذج تحويل لم يتم طرحها بعد، تمريرها سيعيد 400 بدلاً من تجاهلها بصمت. المعلمات الخاصة بالنموذج (`timestamp_granularities[]` لـ `whisper-1`، `languages[]`/`keywords[]` لـ `gpt-transcribe`) ستعيد أيضًا 400 عند تمريرها لنموذج غير مدعوم.
* الطلبات تستغرق وقتًا طويلاً، يُنصح بتعيين مهلة العميل لا تقل عن 300 ثانية.

## رموز الخطأ

| حالة الرمز | code | الوصف |
| - | - | - |
| 400 | `bad_request` | لم يتم تقديم `file`، أو الملف غير قابل للتحليل، أو المعلمات غير صالحة (قيم `model`/`response_format` غير مدعومة، `temperature` تتجاوز 0–1، `timestamp_granularities[]` لم تتوافق مع `verbose_json`، تم تمرير معلمات غير مدعومة لـ `whisper-1`). |
| 401 | `authentication_failed` | الرمز غير صالح. |
| 403 | `used_up` | الرصيد غير كافٍ. |
| 413 | `request_too_large` | ملف الصوت يتجاوز الحد الأقصى 25 ميغابايت. |
| 429 | `too_many_requests` | الطلبات متكررة جدًا، يرجى المحاولة لاحقًا. |
| 500 | `api_error` | خطأ داخلي في الخدمة، يرجى المحاولة لاحقًا. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.