Kolbo Developer API — دليل المطورين الكامل بالعربية

إذا كنت مطوراً يبحث عن واجهة برمجية موحدة تمنحك وصولاً فورياً إلى أكثر من مئة نموذج للذكاء الاصطناعي دون الحاجة إلى إدارة مزودين متعددين، فهذا الدليل كُتب لك تحديداً. Kolbo API ليست مجرد بوابة أخرى — إنها طبقة تجريد كاملة تختصر أسابيع من العمل التكاملي في ساعات.

ما الذي يقدمه Kolbo API؟

المشكلة الكلاسيكية للمطور العربي الذي يريد بناء تطبيق إبداعي: كل نموذج يسكن خادماً مختلفاً، لكل منه توثيق مختلف، وبنية استجابة مختلفة، وسياسة تسعير مختلفة. تريد صورة من Nano Banana 2؟ تتعامل مع مزود. تريد فيديو من Seedance؟ تفتح حساباً آخر. تريد صوتاً من ElevenLabs؟ مفتاح ثالث، توثيق ثالث.

Kolbo API تحل هذه المعادلة بالكامل. مفتاح واحد، بنية طلب موحدة، والنماذج التالية كلها في متناولك: Nano Banana 2، Nano Banana Pro، GPT Image 2، Seedance 2.0، Kling 3.0، Veo 3.1، Suno v5.5، ElevenLabs Scribe v2، Hailuo 2.3، وعشرات غيرها — كل ذلك عبر استدعاء HTTP واحد.

---

البداية السريعة: من الصفر إلى أول صورة في خمس دقائق

الخطوة الأولى: الحصول على مفتاح API

1. سجّل الدخول إلى كولبو.AI
2. انتقل إلى الإعدادات → Developer API
3. أنشئ مفتاحاً جديداً واحفظه — لن يُعرض مرة ثانية

الخطوة الثانية: أول طلب لتوليد صورة

JavaScript (Node.js / Browser):

const response = await fetch('https://api.kolbo.ai/v1/generate/image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'a futuristic Arabic city at sunset, cinematic lighting',
    model: 'nano-banana-2',
    width: 1024,
    height: 1024
  })
});

const { jobId } = await response.json();
// استمر بـ polling للحصول على النتيجة

Python:

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "prompt": "a futuristic Arabic city at sunset, cinematic lighting",
    "model": "nano-banana-2",
    "width": 1024,
    "height": 1024
}

res = requests.post("https://api.kolbo.ai/v1/generate/image",
                    json=payload, headers=headers)
job_id = res.json()["jobId"]

---

نمط العمل: الاستطلاع الدوري (Poll-Based Workflow)

معظم نماذج توليد الذكاء الاصطناعي غير متزامنة — الصورة أو الفيديو لا ينتجان فورياً بل يُعالَجان في طابور. Kolbo API تعتمد نمط poll الصريح:

1. أرسل الطلب → تحصل على jobId
2. استطلع الحالة عبر GET /v1/jobs/{jobId} كل بضع ثوانٍ
3. حالة completed تعني أن الرابط جاهز في حقل outputUrl

import time

def wait_for_result(job_id, api_key, interval=3):
    url = f"https://api.kolbo.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        status_res = requests.get(url, headers=headers).json()
        state = status_res.get("status")

        if state == "completed":
            return status_res["outputUrl"]
        elif state == "failed":
            raise Exception(status_res.get("error", "Job failed"))

        time.sleep(interval)

هذا النمط بسيط، موثوق، ويناسب بيئات الخوادم والتطبيقات المحمولة على حد سواء.

---

Smart Select: دع الـ API يختار النموذج بدلاً منك

الميزة الأذكى في Kolbo API هي Smart Select — بدلاً من تحديد نموذج بعينه، تصف ما تريده وتترك النظام يختار الأنسب:

{
  "prompt": "logo for a tech startup, minimal, dark background",
  "mode": "smart",
  "quality": "high",
  "speed": "balanced"
}

النظام يحلل الطلب ويوجهه تلقائياً نحو النموذج الأمثل بناءً على جودة الخرج المتوقعة، وقت الاستجابة، وتكلفة الاستدعاء. مفيد جداً عند بناء تطبيقات عامة الغرض حيث لا تعرف مسبقاً نوع المحتوى الذي سيطلبه المستخدم.

---

جميع أنواع نقاط النهاية

النوع	المسار	النماذج المدعومة
صورة	/v1/generate/image	Nano Banana 2, Nano Banana Pro, GPT Image 2
فيديو	/v1/generate/video	Seedance 2.0, Kling 3.0, Veo 3.1, Hailuo 2.3
صورة → فيديو	/v1/generate/video-from-image	Seedance, Kling, Hailuo
موسيقى	/v1/generate/music	Suno v5.5, Google Lyria 3 Pro, Minimax
كلام (TTS)	/v1/generate/speech	ElevenLabs, DeepDub
صوت	/v1/generate/sound	ElevenLabs Sound FX
تفريغ نصي	/v1/transcribe	ElevenLabs Scribe v2
تحرير صورة	/v1/edit/image	Inpaint, Background Removal
حالة المهمة	/v1/jobs/{jobId}	جميع المهام

كل نقطة نهاية تعيد بنية موحدة: { jobId, status, outputUrl, metadata } — لا مفاجآت في التنسيق.

---

التسعير وإدارة الاستخدام

Kolbo API تعمل بنظام الاعتمادات (Credits). كل عملية توليد تستهلك عدداً محدداً بناءً على:

• نوع النموذج: نماذج الفيديو أثقل من الصور، والصور الفوتوغرافية الواقعية أثقل من الرسوم التوضيحية
• دقة الخرج: 4K يستهلك أضعاف 1080p
• المدة: الفيديو يُحسب بالثانية

يمكنك تتبع رصيدك عبر:

const usage = await fetch('https://api.kolbo.ai/v1/account/usage', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());

console.log(`الرصيد المتبقي: ${usage.creditsRemaining}`);

نصيحة عملية: اضبط تنبيهات الرصيد من لوحة التحكم لتجنب انقطاع الخدمة في بيئة الإنتاج.

---

دعم MCP للأدوات الذكية

لمن يبني وكلاء AI (Agents) أو أدوات تعمل مع Claude أو GPT-4، تدعم Kolbo API بروتوكول MCP (Model Context Protocol). يتيح هذا للنموذج اللغوي استدعاء أدوات Kolbo مباشرة دون كود وسيط — مثالي لسير العمل الإبداعية الأوتوماتيكية.

---

لمن هذا API؟

• مطورو التطبيقات المحمولة الذين يريدون إضافة ميزات توليد محتوى لتطبيقاتهم
• فرق SaaS التي تبني أدوات تسويقية أو تصميمية مدعومة بالذكاء الاصطناعي
• المستقلون الذين يطورون حلولاً مخصصة لعملاء في قطاعات الإعلام والإعلان
• الشركات الناشئة في المنطقة العربية التي تريد دخول سوق المحتوى الذكي بسرعة دون بنية تحتية معقدة

---

جرّب Kolbo مجاناً الآن

سواء كنت في مرحلة النموذج الأولي أو تبني منتجاً لملايين المستخدمين، Kolbo API توفر لك الأساس التقني الذي يتسع معك. ابدأ بالخطة المجانية، اختبر النماذج، وابنِ أول تكاملاتك قبل أن تدفع سنتاً واحداً.

ابدأ مجاناً على كولبو.AI ←

الحساب المجاني يمنحك اعتمادات تجريبية فورية — لا بطاقة ائتمان مطلوبة.