إنشاء صورة

نظرة عامةCopy Anchor Link

للوكلاء البرمجيين، اكتشف أولًا القائمة القصيرة الموصى بها للصور باستخدام 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 و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-3-pro-image وnano-banana-pro كلًا من aspect_ratio وresolution (1k و2k و4k) في عمليات text-to-image وimage-edit/image-to-image العامة.
• يدعم nano-banana-2 كلًا من aspect_ratio وresolution (1k و2k و4k) في عمليات text-to-image وimage-to-image.
• تدعم gemini-2.5-flash-image وnano-banana وnano-banana-edit الحقل aspect_ratio لكنها لا تعرض اختيار resolution عامًا.
• لطلبات Nano Banana مع صورة مرجعية، استخدم nano-banana-edit أو nano-banana-pro على هذه الواجهة (/v1/images/generations) مع operation: "image-to-image" وimage_urls. لا ترسل طلبات Nano Banana المرجعية إلى /v1/images/edits.
• يمكن إرسال الصور المرجعية في هذه الواجهة عبر 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 كمعرّف توافق لـ grok-imagine-image-quality.

جسم الطلبCopy Anchor Link

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

الاستجابةCopy Anchor Link

الاستجابة المضمنةCopy Anchor Link

استجابة المهمة غير المتزامنةCopy Anchor Link

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

تعيد مهام الصور غير المتزامنة روابط URL للصور النهائية فقط. إذا كنت تحتاج إلى بيانات 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": "gemini-2.5-flash-image",
  "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" وتتطلب polling. راجع حالة الصورة لمعرفة كيفية استرجاع النتائج.

التعامل مع الاستجابات غير المتزامنة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 async
    if data.get("status") in ("pending", "processing"):
        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"},
                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:
        # Sync response
        return data["data"][0]["url"]

# Usage
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"
}