تصویر کی تیاری

Felo image API Felo ماڈل کیٹلاگ کے ماڈلز کے ساتھ تصاویر بناتا اور ایڈٹ کرتا ہے۔ یہ async ہے: جمع کرانے کی درخواست فوراً ایک ٹاسک ID واپس کرتی ہے، اور آپ ٹاسک کو اُس وقت تک پول کرتے ہیں جب تک وہ آخری حالت تک نہ پہنچ جائے۔

یہ صفحہ تصویر سے متعلق مخصوص معاہدے کا احاطہ کرتا ہے۔ مشترکہ ٹاسک لائف سائیکل کے لیے async ٹاسکس دیکھیں۔

شروع کرنے سے پہلے

• ایک API کلید۔ تصدیق دیکھیں۔
• ایسا ماڈل جس کا model_kind image_generation ہو۔ Find an image model دیکھیں۔
• base URL https://openapi.felo.ai۔

یہ OpenAI Images API سے کیسے مختلف ہے

راستہ OpenAI کی Images API سے ملتا جلتا ہے۔ جواب نہیں:

openai.images.generate() کو اِس endpoint پر نہ بھیجیں۔ SDK ہم وقت data ایرے کی توقع رکھتا ہے اور ٹاسک پول نہیں کر سکتا۔ endpoint کو HTTP کے ذریعے کال کریں اور ٹاسک پول کریں، یا دونوں مراحل کے لیے ایک چھوٹا ریپر لکھیں۔

ٹاسک جمع کرائیں

curl -X POST "https://openapi.felo.ai/api/v1/images/generations" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A studio product photo of a ceramic coffee cup on warm linen, soft morning light",
    "resolution": "2K",
    "aspect_ratio": "4:3"
  }'

کامیاب جمع کرانے پر HTTP 202 ملتا ہے:

{
  "task_id": "6d1f0c9a-...",
  "status": "queued",
  "kind": "image",
  "outputs": []
}

202 کا مطلب ہے کہ پلیٹ فارم نے ٹاسک قبول کر لیا۔ اِس کا مطلب نہیں کہ پرامپٹ، پیرامیٹرز یا ریفرنس تصاویر درست ہیں۔ اپ اسٹریم کال جواب کے بعد چلتی ہے، لہٰذا زیادہ تر درخواست کے مسائل بعد میں ناکام ٹاسک کی صورت میں ظاہر ہوتے ہیں۔ استثنا ماڈل روٹنگ ہے: چیٹ یا ویڈیو ماڈل جمع کرانے کے وقت ہی مسترد ہو جاتا ہے۔

ٹاسک آخری حالت تک پول کریں

curl "https://openapi.felo.ai/api/v1/images/generations/${TASK_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"

ٹاسک کی ناکامیوں میں HTTP اسٹیٹس 200 ہی رہتا ہے۔ باڈی میں status چیک کریں، صرف HTTP اسٹیٹس نہیں۔

2–5 سیکنڈ کے وقفے سے آغاز کریں اور وقفہ بڑھاتے جائیں۔ زیادہ تر تصاویر ایک منٹ کے اندر مکمل ہو جاتی ہیں؛ 4K آؤٹ پٹ اور کئی ریفرنس تصاویر والی ایڈیٹنگ میں زیادہ وقت لگتا ہے۔ ہمیشہ اپنی آخری حد مقرر کریں۔

import os
import time

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def generate_image(prompt: str, **params) -> list[dict]:
    response = requests.post(
        f"{BASE}/api/v1/images/generations",
        headers=HEADERS,
        json={"model": "gemini-3-pro-image", "prompt": prompt, **params},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

    deadline = time.monotonic() + 300
    delay = 2.0
    while time.monotonic() < deadline:
        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)

        poll = requests.get(
            f"{BASE}/api/v1/images/generations/{task['task_id']}",
            headers=HEADERS,
            timeout=30,
        )
        poll.raise_for_status()
        task = poll.json()

        if task["status"] == "succeeded":
            return task["outputs"]
        if task["status"] in {"failed", "interrupted"}:
            message = task.get("error", {}).get("message", task["status"])
            raise RuntimeError(message)

    raise TimeoutError(f"image task {task['task_id']} did not finish")

آؤٹ پٹس پڑھیں اور محفوظ کریں

ٹاسک کامیاب ہونے پر outputs میں ہر بنائی گئی تصویر کے لیے ایک اندراج ہوتا ہے:

{
  "task_id": "6d1f0c9a-...",
  "status": "succeeded",
  "kind": "image",
  "outputs": [
    {
      "media_type": "image/png",
      "url": "https://openapi.felo.ai/api/v1/media/...?exp=...&sig=..."
    }
  ]
}

• ٹاسک کامیاب ہونے تک outputs خالی رہتا ہے۔
• url ایک دستخط شدہ URL ہے۔ یہ API کلید کے بغیر ڈاؤن لوڈ ہوتا ہے، لہٰذا اِسے bearer لنک سمجھیں۔
• URL وقتاً محدود ہے۔ exp query parameter اُس کی میعاد کا وقت ہے۔ فائل ڈاؤن لوڈ کریں اور اپنی بکٹ یا فائل سسٹم میں محفوظ کریں؛ ٹاسک مستقل اسٹوریج نہیں۔
• URL کی میعاد ختم ہونے کے بعد دوبارہ پولنگ وہی میعاد ختم شدہ URL واپس کرتی ہے۔ یہ تازہ URL جاری نہیں کرتی۔
• جواب میں base64 تصویری ڈیٹا شامل نہیں ہوتا۔

for index, output in enumerate(outputs):
    image = requests.get(output["url"], timeout=60)
    image.raise_for_status()
    with open(f"image-{index}.png", "wb") as file:
        file.write(image.content)

تصویر ایڈٹ کریں

input_references میں ریفرنس تصاویر بھیجیں۔ ماڈل اُنہیں سیاق و سباق کے طور پر استعمال کرتا ہے؛ پرامپٹ پھر بھی تبدیلی بیان کرتا ہے۔

curl -X POST "https://openapi.felo.ai/api/v1/images/generations" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
    "resolution": "2K",
    "aspect_ratio": "4:3",
    "input_references": [
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/product.png"}
      }
    ]
  }'

ہر ریفرنس ایک HTTP(S) URL یا base64 data URL ہے۔ ریفرنس کی ترتیب برقرار رہتی ہے؛ جب اہم ہو تو پرامپٹ میں تصاویر کا حوالہ اُن کی پوزیشن سے دیں۔ موجودہ ماڈلز زیادہ سے زیادہ 14 ریفرنسز قبول کرتے ہیں۔

درخواست کے فیلڈز

موجودہ تصویری ماڈلز:

کسی فراہم کنندہ کو پن کرنے کے لیے ماڈل کی channels فہرست سے چینل کوڈ کے ساتھ X-Felo-Channel ہیڈر بھیجیں۔ چینلز اور فراہم کنندہ روٹنگ دیکھیں۔

Find an image model (تصویری ماڈل تلاش کریں)

تصویری ماڈلز کی الگ فہرست endpoint نہیں ہے۔ عمومی کیٹلاگ کو استفسار کریں اور model_kind سے فلٹر کریں:

curl "https://openapi.felo.ai/api/v1/models" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  | jq '.data[] | select(.model_kind == "image_generation") | {id, name}'

GET /api/v1/models/{model_id} ماڈل کے چینلز اور شائع شدہ ریٹس واپس کرتا ہے۔

عمومی کیٹلاگ میں supported_parameters پروٹوکول سطح کی فہرست ہے۔ تصویری ماڈلز کے لیے یہ اوپر والے تصویری فیلڈز کو قابل اعتماد طور پر شمار نہیں کرتا، لہٰذا اِس سے اپنی درخواست نہ بنائیں۔ اِس گائیڈ میں دیا گیا فیلڈ ٹیبل استعمال کریں اور کیٹلاگ سے ماڈل ID کی تصدیق کریں۔

قیمت

تصویر جنریشن ماڈل کے شائع شدہ ریٹس سے بل کی جاتی ہے۔ کیٹلاگ ٹیکسٹ prompt اور completion ریٹس کے ساتھ input_image اور output_image بھی ظاہر کرتا ہے۔ تصویری ریٹس ٹوکن ریٹس ہیں: resolution بدلتا ہے کہ ایک تصویر کتنے آؤٹ پٹ تصویری ٹوکنز استعمال کرتی ہے، لہٰذا 4K تصویر 1K سے زیادہ مہنگی ہوتی ہے۔ ریفرنس تصاویر اِن پٹ تصویری ٹوکنز کا اضافہ کرتی ہیں۔

ٹاسک کے جواب میں usage آبجیکٹ شامل نہیں ہوتا۔ چارج کے لیے Console Billing دیکھیں۔

failed یا interrupted پر ختم ہونے والا ٹاسک کوئی آؤٹ پٹ نہیں دیتا اور اُس کا بل نہیں لگتا۔ 402 کے ساتھ مسترد شدہ جمع کرانے سے کوئی ٹاسک نہیں بنا۔

ایررز

تصویر کے راستے سے آنے والے endpoint سطح کے ایررز OpenAI ایرر انویلپ استعمال کرتے ہیں:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

request ID X-Request-Id response ہیڈر میں ہوتا ہے۔ اِسے ٹاسک ID کے ساتھ لاگ کریں۔

تصدیق کے ایررز ایررز، حدود اور دوبارہ کوششیں میں بیان کیے گئے ہیں۔

متعلقہ

• async ٹاسکس
• ماڈلز اور قیمتیں
• چینلز اور فراہم کنندہ روٹنگ
• ایررز، حدود اور دوبارہ کوششیں