وثائق API الخاصة بـ Generor

GET /generators

عرض جميع المولِّدات المتاحة.

curl https://generor.com/api/v1/generators

معاملات الاستعلام: status (active, development, all)

الاستجابة: مصفوفة من المولّدات تحتوي على slug وعنوان ووصف وأيقونة ومولّدات مشابهة.

GET /generators/{slug}

الحصول على معلومات مفصّلة حول مولّد محدد.

curl https://generor.com/api/v1/generators/image

GET /generators/{slug}/creations

تصفّح الإبداعات العامة لمولّد معيّن. يدعم تقسيم الصفحات.

curl "https://generor.com/api/v1/generators/joke/creations?page=1&per_page=10"

POST /generators/{slug}/estimate

عاين تكلفة الرصيد ووقت التوليد المتوقع قبل استدعاء /generate. نفس بنية الجسم مثل /generate — لكنها للقراءة فقط: لا يتم خصم أي رصيد، ولا يتم كتابة أي إبداع. هذا هو نفس الرقم تمامًا الذي تعرضه الواجهة بجانب زر التوليد.

curl -X POST https://generor.com/api/v1/generators/horoscope/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 37,
    "count": 5,
    "parameters": {
      "zodiac-sign": "aries",
      "horoscope-length": "long"
    }
  }'

الاستجابة:

{
  "success": true,
  "data": {
    "generator": "horoscope",
    "model_id": 37,
    "model_type": "text",
    "model_name": "Gemini 3.5 Flash",
    "credit_cost": {
      "total": 15,             // after bulk discount
      "per_item": 3,           // model base × length/quality multipliers
      "count": 5,
      "discount": 0,           // credits saved
      "discount_percent": 5    // % off applied (count% off, capped at 10%)
    },
    "time_estimate": {
      "seconds": 50,           // total wall-clock estimate
      "per_item": 10,
      "min_seconds": 8,
      "max_seconds": 14,
      "sample_count": 10,      // recent generations averaged
      "has_historical": true,
      "source": "historical"   // or "fallback" when sample_count < 3
    },
    "applied_parameters": {    // what the API actually used (schema-filtered)
      "zodiac-sign": "aries",
      "horoscope-length": "long",
      "model-text": "3",
      "horoscope-count": "5"
    }
  }
}

متاح للمستدعين غير المصادَق عليهم — معلومات التسعير/التوقيت عامة وتطابق ما تعرضه صفحة المولّد العامة.

مدد الفيديو المثبّتة

إذا مرّرت قيمة seconds غير موجودة في supported_durations الخاص بالنموذج، يقوم API بمحاذاتها إلى أقرب قيمة مدعومة (وعند التعادل تُختار القيمة الأدنى) ويُظهر التغيير في كتلة adjustments. تعكس تكلفة الرصيد والوقت المُقدّر في الاستجابة نفسها القيمة المحاذاة — أي ما سيفعله /generate فعليًا — وليس الطلب الأصلي.

{
  "success": true,
  "data": {
    "credit_cost": { "total": 30, ... },
    "time_estimate": { "seconds": 60, ... },
    "adjustments": {
      "seconds": {
        "requested": 3,
        "used": 5,
        "supported": [5, 6, 7, 8, 10, 12, 15],
        "reason": "snapped to nearest provider-supported duration"
      }
    }
  }
}

متى تستخدمه

• فحص التكلفة المسبق — تأكّد من قدرة المستخدم على تحمّل تكلفة الإنشاء قبل الخصم.
• واجهة التقدم — أدخِل time_estimate.seconds في شريط التحميل الخاص بك حتى يعرف المستخدمون مدة الانتظار.
• ضبط المعاملات — استدعِه كلما غيّر المستخدم قائمة منسدلة؛ فتُحدَّث التكلفة دون الالتزام بالإنشاء.

العلاقة بـ /generate — /estimate هو استدعاء منفصل، اختياري. يُرجع /generate بالفعل credit_cost الفعلية التي تم فرضها + credits_remaining بعد ذلك، لذا إذا كنت راضيًا عن الدفع بأي سعر مباشر، يمكنك تخطي /estimate تمامًا.

Use the Generor API at https://generor.com/api/v1.

Before calling POST /generators/{slug}/generate, call
POST /generators/{slug}/estimate with the same body to get back:
  - credit_cost.total (credits the next generate call will charge)
  - time_estimate.seconds (expected wall-clock duration)

Show both to the user, then call /generate when they confirm.
The /generate response includes the real credit_cost charged and
credits_remaining — use those to update the user's balance.

Discover each generator's tweakable fields with GET /generators/{slug}
and pass them under the `parameters` object on both /estimate and
/generate (keys match the dropdown IDs you see on the public page).

POST /generators/{slug}/generate AUTH

أنشئ محتوى باستخدام الذكاء الاصطناعي. هذا استدعاء متزامن — تُرجَع الاستجابة عند اكتمال التوليد. يكلّف أرصدة بناءً على النموذج المحدد. يستغرق توليد النص عادةً 5-30 ثانية، وتوليد الصور 10-60 ثانية، وقد يستغرق توليد الفيديو عدة دقائق.

# Text generation (joke with GPT 5 Nano)
curl -X POST https://generor.com/api/v1/generators/joke/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Tell me a joke about programming",
    "model_id": 37
  }'

# Image generation (Flux Schnell, square)
curl -X POST https://generor.com/api/v1/generators/image/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A sunset over mountains",
    "model_id": 10003,
    "aspect_ratio": 1
  }'

# Image description (vision — Qwen VL Max, image-only input, prompt is optional)
curl -X POST https://generor.com/api/v1/generators/vision/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 34,
    "image_url": "https://example.com/photo.jpg",
    "preference": "detailed"
  }'

# Video generation (Happy Horse 1.0 R2V — multi-reference, 6s, wide)
curl -X POST https://generor.com/api/v1/generators/video/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character from [Image1] walks through the forest from [Image2]",
    "model_id": 20050,
    "aspect_ratio": "16:9",
    "seconds": 6,
    "reference_images": [
      "https://example.com/character.jpg",
      "https://example.com/forest.jpg"
    ]
  }'

# Video generation (Happy Horse Video Edit — natural-language edit of an existing clip)
curl -X POST https://generor.com/api/v1/generators/video/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace the sky with a stormy sunset",
    "model_id": 20051,
    "video_url": "https://example.com/source.mp4",
    "seconds": 5
  }'

نص الطلب:

معاملات المولّد

توجد المجموعة الكاملة من الحقول القابلة للضبط لكل مولّد في المخطط خاص بكل مولّد (المصدر نفسه الذي تستخدمه القوائم المنسدلة على الموقع والتعبئة المسبقة عبر URL). مرّر أيًا من تلك الحقول في كائن parameters ضمن طلب التوليد للتحكم بها برمجيًا.

احصل على مخطط أي مولّد عبر GET /generators/{slug} — يسرد مصفوفة parameters في الاستجابة كل حقل مع id وtype (enum أو number أو model) وoptions (أو min/max) وdefault وcost_multipliers.

# 1) Discover the parameters for the horoscope generator
curl https://generor.com/api/v1/generators/horoscope

# 2) Pass them on the generate call
curl -X POST https://generor.com/api/v1/generators/horoscope/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Aries weekly reading",
    "model_id": 37,
    "parameters": {
      "zodiac-sign": "aries",
      "horoscope-timeframe": "weekly",
      "horoscope-tone": "mystical",
      "horoscope-length": "long",
      "horoscope-focus": "career"
    }
  }'

# Image example — every dropdown in the UI is a key here
curl -X POST https://generor.com/api/v1/generators/wallart/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Calm mountain lake at dawn",
    "model_id": 10003,
    "parameters": {
      "wallart-type": "framed-print",
      "wallart-orientation": "landscape",
      "image-aspect-ratio": "4"
    }
  }'

حقول إضافية لتوليد النصوص

بالنسبة لمولّدات النصوص (model_id 1-9999)، تُمرَّر حقول النص الرئيسية التالية إلى نقطة نهاية LLM عند الاقتضاء:

الاستجابة (201 Created) — مثال على مولد النصوص:

{
  "success": true,
  "data": {
    "generator": "joke",
    "model_id": 37,
    "model_type": "text",
    "model_name": "Gemini 3.5 Flash",
    "creations": [
      {
        "creation_id": 6144,
        "text": "Why do programmers prefer dark mode? Because light attracts bugs!",
        "illustration_desc": "a minimalist bug icon on a dark background"
      }
    ],
    "credit_cost": 1,
    "credit_cost_estimated": 1,
    "credits_remaining": 36024,
    "time_taken_seconds": 4.18
  }
}

الاستجابة (201 Created) — مثال على مولد الصور:

{
  "success": true,
  "data": {
    "generator": "image",
    "model_id": 10003,
    "model_type": "image",
    "model_name": "black-forest-labs/flux-schnell",
    "creations": [
      {
        "creation_id": 6147,
        "image_url": "https://generor.com/users/2/img/image-6147.webp"
      }
    ],
    "credit_cost": 24,
    "credit_cost_estimated": 6,
    "credits_remaining": 35998,
    "time_taken_seconds": 23.7
  }
}

مدد الفيديو المثبّتة — إذا لم تكن seconds الخاصة بالمُستدعي ضمن supported_durations للنموذج، فإن API تنتقل إلى أقرب قيمة مدعومة قبل استدعاء المزوّد وتضيف كتلة adjustments.seconds إلى الاستجابة مطابقة في الشكل لتلك الموجودة في /estimate. ويمنع هذا المزوّدين من تعيين القيم غير المدعومة افتراضياً بصمت.

كيف تعمل حقول التكلفة

• credit_cost — المبلغ الفعلي المخصوم، المحسوب كـ balance_before − balance_after. هذا هو مصدر الحقيقة: استخدمه للتسجيل والفوترة وتحديث أرصدة المستخدمين.
• credit_cost_estimated — التقدير المسبق من الكتالوج (نفس الرقم الذي كان /estimate ليتنبأ به). مُدرَج لأغراض الشفافية ومراقبة الانحراف. غالبًا ما يختلف عن credit_cost في تسعير الفيديو / لكل ثانية / لكل حرف حيث يُحسب الرسم الفعلي داخل استدعاء المزوّد.
• time_taken_seconds — المدة الفعلية على مدار الساعة. قارنها بـ time_estimate.seconds من /estimate للتحقق من صحة التنبؤ بالوقت التاريخي.

GET /creations AUTH

عرض إبداعاتك الخاصة.

curl https://generor.com/api/v1/creations \
  -H "Authorization: Bearer gnr_live_..."

معاملات الاستعلام: generator (تصفية حسب slug), page, per_page, sort

GET /creations/public

تصفّح جميع الإبداعات العامة عبر كل المولّدات.

curl "https://generor.com/api/v1/creations/public?generator=image&page=1"

GET /creations/search

ابحث في الإبداعات العامة عبر نص الموجّه.

curl "https://generor.com/api/v1/creations/search?q=sunset+mountain"

GET /creations/{id}

الحصول على إبداع واحد مع تفاصيله الكاملة وصوره والبيانات الخاصة بالمولّد.

curl https://generor.com/api/v1/creations/12345

الإبداعات العامة متاحة للجميع. تتطلب الإبداعات الخاصة المصادقة بصفتك المالك.

تتضمن الاستجابة:

{
  "success": true,
  "data": {
    "creation_id": 12345,
    "generator": "image",
    "user_id": 42,
    "username": "johndoe",
    "prompt": "A sunset over mountains",
    "created_at": "2026-02-20 12:00:00",
    "privacy_mode": 0,
    "type": "img",
    "license": 1,
    "images": [
      {
        "url": "/users/42/img/image-12345.png",
        "width": 1024,
        "height": 1024
      }
    ],
    "generator_data": { ... }
  }
}

GET /creations/{id}/status AUTH

تحقّق من حالة إنشاء إبداع معيّن (مفيد إذا كنت تتتبّع سجلات الإنشاء).

curl https://generor.com/api/v1/creations/12345/status \
  -H "Authorization: Bearer gnr_live_..."

قيم الحالة: pending, generating, completed, failed, cancelled

PATCH /creations/{id} AUTH

تحديث عمل تملكه.

curl -X PATCH https://generor.com/api/v1/creations/12345 \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"privacy_mode": 1, "license": 2}'

DELETE /creations/{id} AUTH

حذف عمل تملكه (حذف ناعم).

curl -X DELETE https://generor.com/api/v1/creations/12345 \
  -H "Authorization: Bearer gnr_live_..."

GET /models

عرض جميع نماذج الذكاء الاصطناعي المتاحة مجمَّعة حسب النوع.

curl https://generor.com/api/v1/models

GET /models/{type}

عرض النماذج لنوع محدد.

curl https://generor.com/api/v1/models/image

الأنواع الصالحة: text, image, video, speech, music, soundeffect, upscale, vector, backgroundremoval

الاستجابة لكل نموذج:

{
  "id": 10001,
  "name": "Flux 1.1 Pro",
  "type": "image",
  "provider": "replicate",
  "description": "High-quality image generation...",
  "credit_cost": 80,
  "supports_img2img": true,
  "supports_aspect_ratio": true
}

نماذج الفيديو تضمّن إضافةً البنية الكاملة لقدرات المزوّد:

{
  "id": 20061,
  "name": "Dreamina Seedance 2.0 (720p)",
  "type": "video",
  "provider": "byteplus",
  "credit_cost": 6,

  // Duration constraints
  "supported_durations": [5, 6, 7, 8, 10, 12, 15],
  "default_duration": 8,

  // Audio toggle
  "supports_audio": true,
  "audio_cost_multiplier": 1,

  // End-frame anchoring (pass `ending_frame_url` on /generate)
  "supports_end_frame": true,

  // Resolution variants — same model at different qualities lives at
  // different model_ids. Switch quality by picking the matching id.
  "quality": "720p",
  "default_quality": "720p",
  "qualities": { "480p": 20060, "720p": 20061, "1080p": 20062 },
  "group_slug": "dreamina-seedance-2-direct",
  "group_name": "Dreamina Seedance 2.0",

  // Aspect ratios accepted on /generate
  "supports_aspect_ratio": true,
  "aspect_ratios": [
    { "id": 1, "ratio": "16:9", "label": "Wide" },
    { "id": 2, "ratio": "9:16", "label": "Tall" }
  ]
}

نماذج الصور التي تختلف في نسبة العرض إلى الارتفاع تتضمن مصفوفة aspect_ratios مكافئة (يحتوي جانب الصورة على 6 إدخالات: مربع، عمودي، أفقي، عريض، طويل، بالإضافة إلى match_input_image لأوضاع img2img).

كيفية استخدام هذه الحقول

• supported_durations — مرّر أي قيمة هنا عبر seconds. تنتقل القيم غير المدعومة على جانب الخادم ويتم الإبلاغ عنها ضمن adjustments.seconds.
• qualities — لتبديل الدقة، ابحث عن model_id للدقة التي تريدها ومرّره كـ model_id الخاص بك. (الدقات هي نماذج شقيقة، وليست معاملًا أثناء التشغيل.)
• supports_audio — عند true، يمكنك تمرير "generate_audio": true على /generate. عند false، يتم تجاهل العلامة.
• supports_end_frame — عند true، يمكنك إقران image_url (إطار البداية) مع ending_frame_url للحصول على انتقالات أو حلقات سلسة.
• aspect_ratios — مرّر id (عدد صحيح) أو ratio (سلسلة نصية) ضمن حقل aspect_ratio في /generate. كلا الصيغتين تعمل.

GET /models/{type}/{id}

الحصول على تفاصيل نموذج محدد وأسعاره.

curl https://generor.com/api/v1/models/image/10001

GET /users/me AUTH

الحصول على ملفك الشخصي ورصيدك من الأرصدة وإحصاءاتك.

curl https://generor.com/api/v1/users/me \
  -H "Authorization: Bearer gnr_live_..."

الاستجابة:

{
  "success": true,
  "data": {
    "user_id": 42,
    "username": "johndoe",
    "email": "john@example.com",
    "avatar": null,
    "bio": "I make things with AI",
    "website": "https://example.com",
    "joined": "2025-01-15 10:30:00",
    "credits": {
      "total": 1250,
      "paid": 1000,
      "free": 200,
      "earned": 50,
      "max": 250
    },
    "creation_count": 347,
    "follower_count": 12,
    "following_count": 5,
    "teams": [...]
  }
}

PATCH /users/me AUTH

حدّث ملفك الشخصي.

curl -X PATCH https://generor.com/api/v1/users/me \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"bio": "Updated bio", "website": "https://example.com"}'

GET /users/{username}

الحصول على الملف الشخصي العام لمستخدم.

curl https://generor.com/api/v1/users/johndoe

GET /users/{username}/creations

عرض الإبداعات العامة لمستخدم. يدعم التقسيم إلى صفحات.

GET /users/{username}/followers

عرض متابِعي مستخدم. يدعم التقسيم إلى صفحات.

GET /users/{username}/following

عرض مَن يتابعهم مستخدم. يدعم التقسيم إلى صفحات.

POST /users/{username}/follow AUTH

متابعة مستخدم.

curl -X POST https://generor.com/api/v1/users/johndoe/follow \
  -H "Authorization: Bearer gnr_live_..."

DELETE /users/{username}/follow AUTH

إلغاء متابعة مستخدم.

GET /users/{username}/follow AUTH

تحقّق مما إذا كنت تتابع مستخدمًا. يُرجع {"following": true/false}.

GET /teams AUTH

عرض فِرقك.

POST /teams AUTH

إنشاء فريق جديد.

curl -X POST https://generor.com/api/v1/teams \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Creative Team"}'

GET /teams/{id} AUTH

الحصول على تفاصيل الفريق مع قائمة الأعضاء.

DELETE /teams/{id} AUTH

مغادرة فريق.

POST /teams/{id}/members AUTH

أضف عضوًا عبر اسم المستخدم: {"username": "janedoe"}

DELETE /teams/{id}/members/{user_id} AUTH

إزالة عضو من الفريق (المالك فقط).

POST /teams/join/{invite_code} AUTH

انضم إلى فريق عبر رمز الدعوة.

POST /teams/{id}/invite AUTH

إعادة توليد رمز الدعوة (المالك فقط).

GET /teams/{id}/creations AUTH

عرض إبداعات الفريق. يدعم التقسيم إلى صفحات.

GET /creations/{id}/comments

عرض التعليقات على إبداع. يدعم التقسيم إلى صفحات.

curl https://generor.com/api/v1/creations/12345/comments

POST /creations/{id}/comments AUTH

أضف تعليقًا.

curl -X POST https://generor.com/api/v1/creations/12345/comments \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Great creation!", "parent_id": null}'

DELETE /comments/{id} AUTH

حذف تعليقك الخاص.

POST /comments/{id}/vote AUTH

صوّت على تعليق: {"vote": "up"} أو {"vote": "down"}

GET /creations/{id}/rating

الحصول على متوسط التقييم لإبداع.

// Response:
{"success": true, "data": {"creation_id": 12345, "average": 4.2, "count": 15}}

POST /creations/{id}/rating AUTH

قيّم إبداعًا (1-5). يحدّث التقييم الحالي إذا سبق تقييمه.

curl -X POST https://generor.com/api/v1/creations/12345/rating \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"score": 5}'

GET /credits/balance AUTH

الحصول على رصيدك الحالي من الأرصدة.

curl https://generor.com/api/v1/credits/balance \
  -H "Authorization: Bearer gnr_live_..."

// Response:
{
  "success": true,
  "data": {
    "total": 1250,
    "paid": 1000,
    "free": 200,
    "earned": 50,
    "max": 250
  }
}

GET /credits/transactions AUTH

الحصول على سجل معاملات الأرصدة.

curl "https://generor.com/api/v1/credits/transactions?type=spend&page=1" \
  -H "Authorization: Bearer gnr_live_..."

معاملات الاستعلام: type (spend, purchase, daily_bonus, weekly_bonus, signup_bonus, refund, gift_sent, gift_received), page, per_page

GET /feed AUTH

الحصول على الإبداعات العامة من المستخدمين الذين تتابعهم.

curl "https://generor.com/api/v1/feed?generator=image&page=1" \
  -H "Authorization: Bearer gnr_live_..."

معاملات الاستعلام: generator (تصفية حسب slug), page, per_page

GET /api-keys AUTH

عرض مفاتيح API الخاصة بك (يُظهر البادئة وليس المفتاح الكامل).

POST /api-keys AUTH

أنشئ مفتاح API جديدًا. يُعرض المفتاح الكامل مرة واحدة فقط في الاستجابة.

curl -X POST https://generor.com/api/v1/api-keys \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "scopes": ["read", "generate"]}'

// Response (201):
{
  "success": true,
  "data": {
    "key_id": 1,
    "api_key": "gnr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "prefix": "gnr_live_a1b2c3d4",
    "name": "My App",
    "scopes": ["read", "generate"],
    "message": "Save this API key now. It will not be shown again."
  }
}

حد أقصى 10 مفاتيح نشطة لكل حساب.

DELETE /api-keys/{id} AUTH

إلغاء مفتاح API (يعطّله فوراً).