واجهة برمجة تطبيقات تحويل الصور إلى برومبت

إذا كنت مطوراً وتريد دمج قدرات تحويل الصور إلى برومبتات AI في تطبيقك أو منصتك، فإن واجهة ImageToPrompt البرمجية توفر لك طريقة بسيطة وفعالة لتحقيق ذلك. في هذا الدليل، سنشرح كيفية استخدام الواجهة البرمجية، ونقدم أمثلة كود عملية بعدة لغات برمجة، ونوضح أفضل الممارسات للتكامل.

نظرة عامة على الواجهة البرمجية

واجهة ImageToPrompt البرمجية هي خدمة REST API تستقبل صوراً وتُرجع برومبتات AI محسّنة لنماذج توليد الصور المختلفة. تعتمد على نموذج Claude Haiku من Anthropic لتحليل الصور بدقة عالية واستخراج عناصرها البصرية وتحويلها إلى أوصاف نصية مُنسَّقة.

تدعم الواجهة البرمجية أربع وظائف رئيسية:

• تحويل صورة إلى برومبت صورة: تحليل صورة وتوليد برومبت مُحسَّن لنموذج AI محدد
• تحويل نص إلى برومبت: تحويل وصف نصي بسيط إلى برومبت احترافي مفصّل
• تحويل صورة إلى برومبت فيديو: تحليل صورة وتوليد برومبت لنماذج توليد الفيديو
• تحويل نص إلى برومبت فيديو: تحويل وصف نصي إلى برومبت فيديو احترافي

نقاط النهاية المتاحة

المصادقة والأمان

تستخدم الواجهة البرمجية مفتاح سري (APP_SECRET) يُرسل في رأس الطلب للمصادقة. هذا يضمن أن الطلبات تأتي من مصادر مُصرَّح لها فقط. كل طلب يجب أن يتضمن الرأس التالي:

x-app-secret: YOUR_APP_SECRET

بدون هذا الرأس أو بمفتاح غير صالح، سيُرجع الخادم خطأ 401 Unauthorized. لا تُشارك مفتاحك السري أبداً في كود الواجهة الأمامية أو المستودعات العامة.

صيغة الطلب

لنقطة النهاية /api/analyze، أرسل طلب POST بجسم JSON يتضمن:

{
  "image": "data:image/jpeg;base64,/9j/4AAQ...",
  "model": "midjourney",
  "style": "cinematic"
}

الحقول المطلوبة:

• image (مطلوب): الصورة بترميز base64 مع بادئة data URI
• model (مطلوب): النموذج الهدف — القيم المقبولة: midjourney، stable-diffusion، flux، dall-e-3، firefly، leonardo، ideogram
• style (اختياري): أسلوب البرومبت — القيم: cinematic، technical، artistic، minimal، epic، photographic

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

تُرجع الواجهة البرمجية استجابة JSON تتضمن البرومبت المُنشأ مع بيانات وصفية إضافية:

{
  "prompt": "cinematic portrait of a woman...",
  "negativePrompt": "blurry, low quality...",
  "creativePrompt": "An ethereal vision of...",
  "colorPalette": ["#2a1f4e", "#7c6bc4", ...],
  "styleTags": ["cinematic", "dramatic"],
  "qualityTags": ["highly detailed", "4k"],
  "aspectRatio": "3:2"
}

أمثلة الكود

Python

import requests
import base64

# Read and encode the image
with open("photo.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://www.imagetoprompt.dev/api/analyze",
    json={
        "image": f"data:image/jpeg;base64,{image_data}",
        "model": "midjourney",
        "style": "cinematic"
    },
    headers={
        "Content-Type": "application/json",
        "x-app-secret": "YOUR_APP_SECRET"
    }
)

result = response.json()
print(result["prompt"])

JavaScript (Node.js)

const fs = require('fs');

const imageData = fs.readFileSync('photo.jpg').toString('base64');

const response = await fetch('https://www.imagetoprompt.dev/api/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-app-secret': 'YOUR_APP_SECRET'
  },
  body: JSON.stringify({
    image: `data:image/jpeg;base64,${imageData}`,
    model: 'stable-diffusion',
    style: 'technical'
  })
});

const result = await response.json();
console.log(result.prompt);

cURL

curl -X POST https://www.imagetoprompt.dev/api/analyze \
  -H "Content-Type: application/json" \
  -H "x-app-secret: YOUR_APP_SECRET" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQ...",
    "model": "flux",
    "style": "photographic"
  }'

حدود الاستخدام

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

• الخطة المجانية: 10 طلبات يومياً لكل عنوان IP
• إعادة التعيين: يُعاد تعيين العداد عند منتصف الليل بتوقيت UTC
• الحد الأقصى لحجم الصورة: 10 ميغابايت
• الصيغ المدعومة: JPEG، PNG، WebP

عند تجاوز الحد، يُرجع الخادم استجابة 429 Too Many Requests مع رسالة توضح وقت إعادة التعيين.

معالجة الأخطاء

تُرجع الواجهة البرمجية رموز حالة HTTP قياسية مع رسائل خطأ وصفية بصيغة JSON:

أفضل الممارسات للتكامل

• ضغط الصور قبل الإرسال: قلّل حجم الصورة إلى أقل من 2 ميغابايت لأوقات استجابة أسرع. الجودة 85% في JPEG كافية تماماً للتحليل الدقيق
• تخزين النتائج مؤقتاً: إذا كنت تُحلل نفس الصورة لنماذج متعددة، خزّن النتائج مؤقتاً لتقليل الطلبات المكررة
• معالجة الأخطاء بأناقة: نفّذ آلية إعادة محاولة تلقائية مع تأخير تصاعدي للأخطاء 500
• لا تُضمّن المفتاح السري في كود الواجهة: استخدم خادماً وسيطاً (proxy) لإخفاء مفتاحك عن المستخدمين النهائيين
• تحقق من صيغة الصورة: تأكد من أن الصورة بصيغة مدعومة (JPEG أو PNG أو WebP) قبل ترميزها بـ base64

أسئلة شائعة

ما هي واجهة برمجة تطبيقات ImageToPrompt؟

واجهة برمجة تطبيقات ImageToPrompt هي API تتيح للمطورين تحويل الصور إلى برومبتات AI برمجياً. ترسل صورة بترميز base64 وتحصل على برومبت محسّن للنموذج الذي تختاره مثل Midjourney أو Stable Diffusion أو Flux أو DALL-E 3.

ما هي حدود استخدام الواجهة البرمجية؟

الخطة المجانية تسمح بـ 10 طلبات يومياً لكل عنوان IP. تشمل حدود الصورة حجماً أقصى 10 ميغابايت وصيغ JPEG وPNG وWebP. وقت الاستجابة يتراوح بين 5-15 ثانية حسب تعقيد الصورة.

هل يمكنني دمج الواجهة البرمجية في تطبيقي؟

نعم، الواجهة البرمجية مصممة للتكامل مع أي تطبيق. تدعم طلبات REST عبر HTTP POST مع جسم JSON. يمكنك استخدامها من أي لغة برمجة تدعم طلبات HTTP مثل Python وJavaScript وRuby وPHP وغيرها.

هل الصور التي أرسلها للواجهة البرمجية محفوظة؟

لا، جميع الصور المُرسلة للواجهة البرمجية تُعالج بشكل مؤقت ولا تُخزَّن على خوادمنا. التحليل سريع الزوال وخاص تماماً. لا نحتفظ بأي بيانات صور بعد إتمام التحليل وإرجاع النتيجة.