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

واجهة API واحدة شاملة لكل مهام معالجة الملفات

توفّر Converter App للمطوّرين واجهة عالية الأداء لمعالجة الملفات. استبدل الأدوات المنفصلة بواجهة API واحدة لتحويل المستندات، ومعالجة الوسائط، ونسخ المحتوى صوتيًا، والتعرّف الضوئي على الحروف بشكل قابل للتوسّع.

احصل على الوصول

نظرة عامة على واجهة برمجة التطبيقات في Converter App

توفر واجهة برمجة التطبيقات الخاصة بـ Converter App للمطورين واجهة عالمية وسلسة لجميع احتياجات معالجة الملفات. وبدلاً من دمج مجموعة مجزأة من الأدوات المنفصلة، يمكن لتطبيقك استدعاء خدمة واحدة عالية الأداء. يمكنك دمج مجموعة المحولات الكاملة لدينا مباشرةً في مهام سير عمل الواجهة الخلفية للتعامل مع كل شيء، من تغييرات الملفات القياسية إلى مهام الوسائط الشاقة.

عنوان URL الأساسي العام هو https://api.converter.app/. وتستخدم المسارات في هذا المستند جذر واجهة برمجة التطبيقات المقدم خارجيًا هذا.

تغطية شاملة

الوصول إلى مكتبة متكاملة من أدوات التحويل عبر تكامل واحد مبسّط.

وضعا معالجة

اختر الطلبات المتزامنة للحصول على استجابات فورية، أو المهام غير المتزامنة للملفات الكبيرة والمهام طويلة التشغيل.

مصمم خصيصًا لتلبية احتياجاتك

تواصل معنا، ويمكننا أن نقدم لك خطة مصممة خصيصًا لاحتياجاتك بسعر لا يُضاهى.

المستندات الصور الصوت الفيديو نص الأرشيفات

اكتشف التحويلات المدعومة (لا يلزم مفتاح)

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

احصل على /public/pairs

نقطة النهاية هذه مفتوحة، بحيث يمكن للمطورين الاطلاع على فهرس التحويل الشامل قبل طلب مفتاح API أو إعدادِه.

curl "https://api.converter.app/public/pairs"

JavaScript

const response = await fetch('https://api.converter.app/public/pairs');
const pairs = await response.json();
console.log(pairs.supported_pairs);

Python

import requests

response = requests.get('https://api.converter.app/public/pairs')
response.raise_for_status()
pairs = response.json()
print(pairs['supported_pairs'])

مثال على الرد

{
  "supported_pairs": [
    { "from": "mp3", "to": "text" },
    { "from": "mp4", "to": "mp3" },
    { "from": "mov", "to": "mp4" },
    { "from": "wav", "to": "mp3" },
    { "from": "mkv", "to": "mp4" }
  ]
}

المصادقة والتحكم في الوصول

يقوم المطوّرون بالمصادقة عن طريق تمرير مفتاح API الخاص بهم في ترويسة HTTP X API Key. إن نقطة النهاية العامة /public/pairs هي نقطة النهاية الوحيدة في هذه الصفحة التي لا تتطلب مفتاحًا.

التحكمكيف يعملأثر المطورين
X-API-Keyأرسل المفتاح كعنوان طلب HTTP.مطلوب لـ /pairs و/convert/sync و/convert و/progress/{jobid} و/download/{jobid}.
حصص الاستخداملكل مفتاح حصة تحويل رقمية. تنخفض الحصة عند إنشاء مهام التحويل.يمنح الحصص البالغة -1 تحويلات غير محدودة. وتمثل القيم الأخرى عدد التحويلات المسموح بها المتبقية.
الأزواج المسموح بهايمكن تقييد المفاتيح بأنواع تحويل محددة مثل mp42mp3، أو منحها إمكانية الوصول إلى جميع الأزواج المدعومة عبر all./pairs تُرجِع فقط الأزواج التي يكون مفتاحكم مخوّلًا لاستخدامها، وتُرفَض طلبات التحويل خارج تلك القائمة.
 
curl "https://api.converter.app/pairs" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/pairs', {
  headers: {
    'X-API-Key': apiKey
  }
});

const pairs = await response.json();
console.log(pairs);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get('https://api.converter.app/pairs', headers=headers)
response.raise_for_status()
print(response.json())

2. التحويل المتزامن

منشور /convert/sync

استخدم التحويل المتزامن عندما تريد نتيجة فورية في استجابة HTTP نفسها. يبقى الطلب مفتوحًا بينما يبدأ واجهة برمجة التطبيقات مهمة التحويل وينتظر اكتمالها، لمدة تصل إلى 30 دقيقة.

حقل النموذجالنوعالوصف
target_formatstringامتداد الإخراج المطلوب، مثل pdf أو docx أو mp3 أو jpg.
filesملف[]ملف مصدر واحد أو أكثر تم رفعه. تحدد واجهة برمجة التطبيقات التنسيق المصدر من اسم الملف الذي تم رفعه.
 
curl -X POST "https://api.converter.app/convert/sync" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=pdf" \
  -F "files=@/path/to/document.docx" \
  -o converted.pdf

JavaScript

const form = new FormData();
form.append('target_format', 'pdf');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert/sync', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const convertedFile = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'pdf'}

with open('/path/to/document.docx', 'rb') as document:
    files = {'files': document}
    response = requests.post(
        'https://api.converter.app/convert/sync',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
with open('converted.pdf', 'wb') as output:
    output.write(response.content)

يتم بثّ الملف المحوَّل مباشرةً في الاستجابة. وإذا أدّى التحويل إلى إنشاء عدة ملفات، فإن واجهة برمجة التطبيقات تُرجع أرشيف .zip.

3. التحويل غير المتزامن

POST /convert

استخدم التحويل غير المتزامن للملفات الكبيرة، أو المعالجة الدفعية، أو مهام الصوت أو الفيديو طويلة التشغيل، أو تطبيقات الإنتاج التي لا ينبغي أن تُبقي طلبات الرفع مفتوحة أثناء تنفيذ العمل.

حقل النموذجالنوعالوصف
target_formatسلسلةتنسيق الإخراج المطلوب. يشكّل المصدر والهدف زوج التحويل، على سبيل المثال mp42mp3.
filesfile[]ملف واحد أو أكثر للتحويل.

cURL

curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

جافا سكريبت

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const job = await response.json();
console.log(job.jobid, job.remaining_quota);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
job = response.json()
print(job['jobid'], job['remaining_quota'])

استجابة النجاح

{
  "status": "success",
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "pair": "mp42mp3",
  "remaining_quota": 42
}

4. تتبع الحالة

احصل على /progress/{jobid}

استعلم عن نقطة النهاية هذه بعد إنشاء مهمة غير متزامنة. فهي تُرجع حالة المهمة، وقيمة تقدّم رقمية من 0.0 إلى 1.0، وتفاصيل الخطأ إذا فشل التحويل.

الرأسالوصف
X-API-Keyمفتاح واجهة برمجة التطبيقات للمطور لديك.
 
curl "https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const progress = await response.json();
console.log(progress.status, progress.progress);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()
progress = response.json()
print(progress['status'], progress['progress'])
{
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "progress": 1.0,
  "status": "completed",
  "error": null
}

الحالات الممكنة هي processing وcompleted وfailed. التقدم هو رقم بين 0.0 و1.0.

5. استرجاع الملفات

احصل على /download/{jobid}

بمجرد أن تصل مهمة غير متزامنة إلى completed، استرجع الناتج المحوَّل باستخدام مفتاح API نفسه المستخدم لإنشاء المهمة.

نوع النتيجةالسلوك
ملف إخراج واحديقوم واجهة برمجة التطبيقات ببث الملف المحوَّل مباشرةً.
resultfile البيان إذا كانت المهمة توفر بيان نتائج، فستُرجِع واجهة برمجة التطبيقات الملف المحدد في ذلك البيان.
ملفات إخراج متعددةتقوم واجهة برمجة التطبيقات بتجميع الملفات المُنشأة في أرشيف .zip تلقائيًا أثناء التنفيذ.
 
curl -L "https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o converted-output.zip

JavaScript

const response = await fetch('https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const file = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()

with open('converted-output.zip', 'wb') as output:
    output.write(response.content)

ملخص سير عمل المطوّر

يدعم واجهة برمجة التطبيقات نمطي تكامل، بحيث يمكن للمطورين اختيار السلوك المناسب لكل حالة استخدام.

سير العملنمط الطلبالأفضل لـ
تدفق المزامنة السريعPOST /convert/sync يعرض الملف المحوَّل في نفس الاستجابة.الملفات الصغيرة، نصوص سطر الأوامر، النماذج الأولية، والأتمتة البسيطة من جانب الخادم.
تدفق غير متزامن قويPOST /convert، ثم استعلم دوريًا عن GET /progress/{jobid}، ثم استدعِ GET /download/{jobid}.ملفات الفيديو أو الصوت الكبيرة، والتحويل الدفعي، وخلفيات تطبيقات الويب، وأنظمة الإنتاج المتوافقة مع إعادة المحاولة.

مثال على التدفق غير المتزامن

# 1. Start the job
curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

# 2. Poll until completed
curl "https://api.converter.app/progress/JOBID" \
  -H "X-API-Key: YOUR_API_KEY"

# 3. Download the finished output
curl -L "https://api.converter.app/download/JOBID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o result.mp3

JavaScript

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const createResponse = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});
const job = await createResponse.json();

const progressResponse = await fetch(`https://api.converter.app/progress/${job.jobid}`, {
  headers: {
    'X-API-Key': apiKey
  }
});
const progress = await progressResponse.json();

if (progress.status === 'completed') {
  const downloadResponse = await fetch(`https://api.converter.app/download/${job.jobid}`, {
    headers: {
      'X-API-Key': apiKey
    }
  });
  const result = await downloadResponse.blob();
}

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    create_response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

create_response.raise_for_status()
job = create_response.json()

progress_response = requests.get(
    f"https://api.converter.app/progress/{job['jobid']}",
    headers=headers
)
progress_response.raise_for_status()
progress = progress_response.json()

if progress['status'] == 'completed':
    download_response = requests.get(
        f"https://api.converter.app/download/{job['jobid']}",
        headers=headers
    )
    download_response.raise_for_status()
    with open('result.mp3', 'wb') as output:
        output.write(download_response.content)

استجابات الأخطاء

تُعاد الأخطاء على هيئة JSON مع حقل detail، باستخدام رموز حالة HTTP القياسية.

الحالةالسبب الشائع
400ملفات مفقودة، أو target_format مفقود، أو تنسيق معرّف المهمة غير مدعوم، أو إدخال طلب غير صالح.
401X API Key مفقود أو غير صالح.
403مفتاح API غير مسموح له باستخدام زوج التحويل المطلوب.
404الوظيفة المطلوبة أو ملف النتيجة المُنشأ غير متاح.
409لا تزال عملية التحويل قيد المعالجة عند طلب التنزيل.
429لم يتبقَّ أيّ رصيد متاح لمفتاح واجهة برمجة التطبيقات.
500تعذّر إعداد التحويل أو إكماله بسبب خطأ في المعالجة من جهة الخادم.
 
{
  "detail": "This API key is not authorized for mp42mp3 conversions."
}