إنشاء صورة

نظرة عامةCopy Anchor Link

استخدم GET /v1/models?recommended_for=image للحصول على نماذج الصور الحالية، ثم أرسل الـ model المختار بشكل صريح.

gpt-image-2 هو نموذج GPT Image يعتمد على نظام تسعير الرموز (tokens). يتبع TokenLab تفصيل الاستخدام الرسمي لـ OpenAI لرموز إدخال النص، وإدخال الصورة، ورموز الإدخال المخزنة مؤقتاً (cached input)، ورموز إخراج الصورة؛ ولا تتم محاسبته كنموذج بسعر ثابت لكل صورة.

بالنسبة لإنشاء الصور باستخدام gpt-image-2، فإن المعلمات (parameters) العامة المدعومة هي prompt و n و size و quality و response_format و async و background و output_format و output_compression أو compression و moderation و user. تقبل background القيمة auto أو opaque؛ بينما لا يتم دعم transparent. قم بحذف size أو quality للسماح لـ TokenLab باستخدام auto؛ يجب أن تستخدم قيم size المخصصة عقد WIDTHxHEIGHT المرن الموثق أدناه.

input_fidelity ليست جزءاً من الحقول المدعومة حالياً في TokenLab لنموذج gpt-image-2؛ قم بحذفها وإلا سيعيد الطلب 400 unsupported_parameter.

ملاحظات حول سلوك النموذجCopy Anchor Link

لا تشترك نماذج عائلة صور Google Gemini في نفس عقد اختيار النموذج:

• تدعم gemini-3.1-flash-image و gemini-nano-banana-2.1 و gemini-3-pro-image و nano-banana-2.1 و nano-banana-pro كلاً من aspect_ratio بالإضافة إلى resolution (1k, 2k, 4k) لعملياتها العامة من نص إلى صورة، ومن صورة إلى صورة، وتعديل الصور.
• تدعم nano-banana-2 كلاً من aspect_ratio و resolution (1k, 2k, 4k) لكل من عمليات إنشاء من نص إلى صورة ومن صورة إلى صورة.
• تدعم gemini-3.1-flash-lite-image و nano-banana-2-lite عمليات من نص إلى صورة، ومن صورة إلى صورة، وتعديل الصور بدقة 1k فقط.
• تدعم nano-banana خاصية aspect_ratio ولكنها لا تكشف عن اختيار resolution عام.
• بالنسبة لعمليات من صورة إلى صورة مع gemini-3.1-flash-image أو gemini-nano-banana-2.1 أو gemini-3.1-flash-lite-image أو gemini-3-pro-image، استخدم هذا الـ endpoint مع operation: "image-to-image" وصور مرجعية. أرسل طلبات تعديل الصور لهذه النماذج إلى /v1/images/edits.
• بالنسبة لطلبات الصور المرجعية لـ Nano Banana، استخدم nano-banana-2 أو nano-banana-2.1 أو nano-banana-2-lite أو nano-banana-pro على هذا الـ endpoint (/v1/images/generations) مع operation: "image-to-image" و image_urls. تستخدم طلبات تعديل الصور لـ nano-banana-2 و nano-banana-2.1 و nano-banana-2-lite و nano-banana-pro هذا الـ endpoint أيضاً، مع operation: "image-edit". لا ترسل طلبات الصور المرجعية لـ Nano Banana إلى /v1/images/edits.
• يمكن توفير الصور المرجعية على هذا الـ endpoint كـ image_url / image_urls بتنسيق JSON، أو كملف image متعدد الأجزاء (multipart). لا يتم قبول images[] و file_id على /v1/images/generations؛ قم بإنشاء مراجع /v1/files فقط لنماذج /v1/images/edits التي توثق images[].file_id.

بالنسبة لعائلات صور Google، يفضل استخدام aspect_ratio وإرسال resolution فقط عندما يدعمها النموذج بشكل صريح.

تدعم نماذج صور xAI Grok Imagine (grok-imagine-image و grok-imagine-image-2.0 و grok-imagine-image-pro القديم) خاصية aspect_ratio بالإضافة إلى resolution (1k, 2k). يتم الاحتفاظ بـ grok-imagine-image-pro كمعرف توافق لـ grok-imagine-image-2.0.

جسم الطلب (Request Body)Copy Anchor Link

مهلة الطلب المتزامن (Synchronous request timeout): تعيد بعض طلبات الصور الصورة النهائية بشكل مضمن وتنتظر حتى انتهاء الإنشاء. قد تستغرق الطلبات عالية الدقة أو عالية الجودة ما يقرب من دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP الخاص بك على 120s على الأقل. إذا كان رد الإنشاء يتضمن status: "pending" أو task_id أو poll_url، فاتبع poll_url المرجعة بدلاً من ذلك.

الاستجابة (Response)Copy Anchor Link

الاستجابة المضمنة (Inline Response)Copy Anchor Link

استجابة المهمة غير المتزامنة (Async Task Response)Copy Anchor Link

اضبط async: true مع gpt-image-2 أو نماذج صور FLUX/BFL الرسمية لإنشاء مهمة بدلاً من انتظار الصورة النهائية في طلب الإنشاء. تتضمن الاستجابة status: "pending" و task_id و poll_url. قم بعمل استطلاع (poll) لـ /v1/tasks/{task_id} حتى تصل المهمة إلى completed أو failed.

تعيد مهام الصور غير المتزامنة روابط الصور النهائية فقط. إذا كنت بحاجة إلى بيانات صورة b64_json خام، استخدم طلباً متزامناً.

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

عندما تتلقى 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",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)

print(response.data[0].url)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.generate({
  model: 'gemini-3-pro-image',
  prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
  aspect_ratio: '16:9',
  resolution: '2k'
});

console.log(response.data[0].url);

<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gemini-3-pro-image',
        'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
        'aspect_ratio' => '16:9',
        'resolution' => '2k'
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

{
  "model": "nano-banana",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

{
  "model": "nano-banana-pro",
  "prompt": "Create a clean cinematic character image based on the reference images",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/reference-1.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=nano-banana-pro" \
  -F "prompt=Create a clean cinematic character image based on this reference" \
  -F "operation=image-to-image" \
  -F "image=@reference.png" \
  -F "aspect_ratio=1:1" \
  -F "resolution=2k"

{
  "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..."
    }
  ]
}

اختيار نموذجCopy Anchor Link

استعلم عن GET /v1/models?recommended_for=image أو استخدم صفحة النماذج لمعرفة التوفر الحالي والقدرات والأسعار.

لا تقم ببرمجة نموذج ليكون متزامناً دائماً أو غير متزامن دائماً. إذا أعاد رد الإنشاء status: "pending"، فاتبع poll_url وقم بالاستطلاع حتى الاكتمال.

التعامل مع الاستجابات القائمة على المهامCopy Anchor Link

بالنسبة لنماذج الصور، تحقق دائماً مما إذا كانت الاستجابة تحتوي على status: "pending" / status: "processing":

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # 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, "async": True},
        timeout=120
    )
    response.raise_for_status()
    data = response.json()

    # Check if task-based
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Image 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"},
                timeout=30
            )
            status_resp.raise_for_status()
            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:
        # Inline response
        return data["data"][0]["url"]

# الاستخدام
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}