الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
نظرة عامة

للوكلاء البرمجيين، اكتشف أولًا القائمة القصيرة الموصى بها للصور باستخدام GET /v1/models?recommended_for=image، ثم أرسل model المختار صراحةً إلى هذه النقطة النهائية. gpt-image-2 هو نموذج GPT Image تُحسب تكلفته حسب الـ tokens. تتبع TokenLab تفاصيل usage الرسمية من OpenAI لتسوية tokens إدخال النص، وإدخال الصور، والإدخال المخزن مؤقتًا عند الإبلاغ عنه، وtokens إخراج الصور؛ ولا يتم التعامل معه كنموذج بسعر ثابت لكل صورة. بالنسبة إلى إنشاء الصور باستخدام gpt-image-2، تدعم الواجهة العامة المعلمات prompt وn وsize وquality وresponse_format وasync وbackground وoutput_format وoutput_compression أو compression وmoderation وpartial_images وuser. إذا لم ترسل size أو quality تستخدم TokenLab القيمة auto؛ ويجب أن تستخدم قيم size المخصصة عقد WIDTHxHEIGHT المرن الموضح أدناه. ملاحظة توافق: إذا أرسل طلب gpt-image-2 الحقل input_fidelity، تزيله TokenLab قبل التمرير لأن GPT Image 2 يعالج مدخلات الصور تلقائيا بدقة عالية.

​
ملاحظات سلوك النموذج

Google Gemini في عقد اختيار واحد:
  • gemini-3.1-flash-image-preview و gemini-3-pro-image-preview و nano-banana-2 و nano-banana-pro تدعم aspect_ratio مع resolution (1k و 2k و 4k) لتوليد الصور من النص.
  • gemini-2.5-flash-image و nano-banana و nano-banana-edit تدعم aspect_ratio لكنها لا تعرض اختيارًا عامًا لـ resolution.
  • gemini-2.0-flash-preview-image-generation موثّق هنا على أنه تحويل نص إلى صورة يعتمد على prompt فقط.
  • لطلبات الصور المرجعية مع nano-banana وnano-banana-2 وnano-banana-pro، استخدم هذه الواجهة (/v1/images/generations) مع operation: "image-to-image" وimage_urls. لا ترسل طلبات Nano Banana المرجعية إلى /v1/images/edits.
  • في طلبات image-to-image الخاصة بـ Nano Banana، احذف resolution. يتيح nano-banana-2 وnano-banana-pro هذا الحقل فقط لتوليد الصور من النص، ولا يتيحه nano-banana.
  • يمكن إرسال الصور المرجعية في هذه الواجهة عبر JSON image_url / image_urls أو كملف multipart باسم image. لا تقبل /v1/images/generations الحقول images[] أو file_id؛ تُستخدم مراجع /v1/files فقط مع نماذج /v1/images/edits التي توثق images[].file_id صراحةً.
لأسَر صور Google، فضّل aspect_ratio وأرسل resolution فقط عندما يذكرها النموذج صراحةً. نماذج صور xAI Grok Imagine (grok-imagine-image وgrok-imagine-image-quality وgrok-imagine-image-pro القديم) تدعم aspect_ratio مع resolution (1k و2k). يبقى grok-imagine-image-pro كمعرّف توافق ويتم توجيهه upstream إلى grok-imagine-image-quality.

​
جسم الطلب

مهلة الطلبات المتزامنة: قد يعيد بعض مزودي الصور الذين يتم التوجيه إليهم الصورة النهائية inline وينتظرون اكتمال التوليد. قد تستغرق طلبات الدقة العالية أو الجودة العالية ما يقارب دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP على 120s على الأقل. إذا احتوت استجابة الإنشاء على status: "pending" أو task_id أو poll_url، فاتبع poll_url المُعاد بدلًا من الانتظار.
​
model
string
افتراضي:"dall-e-3"
النموذج المطلوب استخدامه (مثل gpt-image-2 أو dall-e-3 أو flux-pro أو midjourney).
​
prompt
string
مطلوب
وصف نصي للصورة المطلوبة.
​
image_url
string
رابط HTTPS عام لصورة مرجعية في توليد image-to-image. لعائلة Nano Banana، اجعل operation تساوي image-to-image واحذف resolution ما لم يكن النموذج يدعمها صراحةً لهذه العملية.
​
image_urls
string[]
روابط HTTPS عامة لصور مرجعية. استخدمها لصورة مرجعية واحدة أو أكثر في طلبات JSON. لا تدعم هذه الواجهة file_id أو images[].
​
reference_image_urls
string[]
روابط صور مرجعية إضافية خاصة بالنموذج للمزوّدين الذين يميزون بين صورة الإدخال الأساسية والصور المرجعية.
​
image
file
ملف صورة مرجعية multipart لتوليد image-to-image. استخدمه عندما تكون الصورة المصدر خاصة أو تتطلب ترويسات. هذا يختلف عن file_id من /v1/files؛ هذه الواجهة لا تقبل file_id.
​
n
integer
افتراضي:"1"
عدد الصور المطلوب إنشاؤها (1-10، بحسب النموذج).
​
size
string
افتراضي:"1024x1024"
حجم الصورة. استخدمه لعائلات الصور بأسلوب OpenAI والنماذج الأخرى التي تقبل أحجام بكسل دقيقة.بالنسبة إلى gpt-image-2، تقبل size القيمة auto أو WIDTHxHEIGHT. يجب أن يكون كل من البعدين من مضاعفات 16، وألا يتجاوز أطول ضلع 3840px، وألا تتجاوز نسبة الضلع الطويل إلى القصير 3:1، وأن يكون إجمالي عدد البكسلات بين 655,360 و8,294,400. لا تُعد aspect_ratio وresolution جزءًا من العقد العام الحالي في TokenLab لـ gpt-image-2.بالنسبة إلى عائلات صور Google Gemini، يتم التعامل مع size كاسم بديل للتوافق يطابق عقد aspect_ratio العام للنموذج، وresolution عند دعمه. لهذه النماذج، يُفضّل إرسال aspect_ratio مباشرةً.
​
aspect_ratio
string
محدد نسبة الأبعاد بحسب النموذج.القيم الشائعة في عائلات صور Google تشمل 1:1 و 16:9 و 9:16 و 3:2 و 2:3.
​
resolution
string
محدد دقة الإخراج بحسب النموذج.مدعوم في gemini-3.1-flash-image-preview وgemini-3-pro-image-preview وnano-banana-2 وnano-banana-pro وعائلات الدقة العالية المشابهة. القيم النموذجية هي 1k و2k و4k. لا ترسل هذه المعلمة إلى عائلات صور Gemini التي تدعم النسبة فقط إلا إذا وثّقها النموذج صراحةً. لنماذج صور xAI Grok Imagine استخدم 1k أو 2k.
​
quality
string
افتراضي:"standard"
جودة الصورة. تستخدم نماذج DALL-E القيمتين standard أو hd؛ أما نماذج GPT Image مثل gpt-image-2 فتستخدم auto أو low أو medium أو high.
​
response_format
string
افتراضي:"url"
تنسيق الاستجابة: url أو b64_json. القيمة الافتراضية هي url.بالنسبة إلى مسارات gpt-image-2 على Azure Official أو القنوات المتوافقة مع Azure، لا تمرّر TokenLab الحقل response_format إلى upstream. يحصل gateway دائمًا على بيانات الصور من upstream بصيغة b64_json؛ عند طلب url يرفع كل صورة إلى CDN ويعيد data[].url. إذا لم يكن تخزين CDN متاحًا أو فشل الرفع، يفشل الطلب بدلاً من الرجوع إلى Base64. عند طلب b64_json يُعاد Base64 الخام.
​
async
boolean
افتراضي:"false"
اضبطه على true مع gpt-image-2 أو نماذج الصور الرسمية FLUX/BFL لإنشاء مهمة أولاً. تعيد مهام الصور غير المتزامنة المكتملة روابط URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة إذا كنت تحتاج إلى b64_json.
​
style
string
افتراضي:"vivid"
النمط لـ DALL-E 3: vivid أو natural.
​
user
string
معرّف فريد للمستخدم النهائي.

​
الاستجابة

​
الاستجابة المتزامنة (DALL-E, Flux Schnell, إلخ.)

​
created
integer
الطابع الزمني Unix لوقت الإنشاء.
​
data
array
مصفوفة من الصور المُنشأة.يحتوي كل كائن على:
  • url (string): عنوان URL للصورة المُنشأة
  • b64_json (string): صورة مرمّزة بـ Base64 (إذا تم طلبها)
  • revised_prompt (string): الـ prompt المستخدم (DALL-E 3)

​
استجابة المهمة غير المتزامنة

اضبط async: true مع gpt-image-2 أو نماذج الصور الرسمية FLUX/BFL لإنشاء مهمة بدلاً من انتظار الصورة النهائية داخل طلب الإنشاء. تتضمن الاستجابة status: "pending" وtask_id وpoll_url. استعلم عن /v1/tasks/{task_id} حتى تصل المهمة إلى completed أو failed. تعيد مهام الصور غير المتزامنة روابط URL للصور النهائية فقط. إذا كنت تحتاج إلى بيانات b64_json الخام، فاستخدم طلبًا متزامنًا. قد يتم حجز التكلفة المقدّرة عند إنشاء المهمة. تُحاسب المهام المكتملة حسب الاستخدام الفعلي، وتُحرر أو تُسترد تكلفة المهام الفاشلة أو المنتهية بالمهلة.
​
created
integer
طابع Unix الزمني لوقت الإنشاء.
​
task_id
string
معرّف المهمة الفريد للاستطلاع.
​
status
string
الحالة الأولية: pending.
​
poll_url
string
عنوان URL نسبي للاستطلاع للحصول على النتائج، على سبيل المثال /v1/tasks/{id}.
​
data
array
يبقى فارغًا أثناء كون المهمة قيد الانتظار. وتُرجِع مهام الصور المكتملة عناوين URL للصور المُولَّدة في data[].url.
عند تلقي status: "pending"، استخدم poll_url أو GET /v1/tasks/{task_id} لاسترداد النتيجة. 
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}

​
النماذج المتاحة

النموذجالنوعالميزات
dall-e-3متزامنأفضل جودة، تحسين الـ prompt
dall-e-2متزامنأسرع وأكثر توفيرًا
flux-proغير متزامنواقعي تصويريًا، جودة عالية
flux-schnellمتزامنسريع جدًا
midjourneyغير متزامننمط فني
ideogram-v3غير متزامنأفضل عرض للنصوص
stable-diffusion-3متزامنمفتوح المصدر، قابل للتخصيص
النماذج غير المتزامنة تُرجع status: "pending" وتتطلب polling. راجع حالة الصورة لمعرفة كيفية استرجاع النتائج.

​
التعامل مع الاستجابات غير المتزامنة

بالنسبة للنماذج غير المتزامنة، تحقّق مما إذا كانت الاستجابة تحتوي على status: "pending": 
import requests
import time

def generate_image(prompt, model="midjourney"):
    # Create image request
    response = requests.post(
        "https://api.tokenlab.sh/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt}
    )
    data = response.json()

    # Check if async
    if data.get("status") == "pending":
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Async task started: {task_id}")

        # Poll for result
        while True:
            status_resp = requests.get(
                f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"}
            )
            status_data = status_resp.json()

            if status_data["status"] == "completed":
                return status_data["data"][0]["url"]
            elif status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)
    else:
        # Sync response
        return data["data"][0]["url"]

# Usage
url = generate_image("a beautiful sunset over mountains", model="midjourney")
print(f"Generated image: {url}")