इमेज जनरेशन

Felo इमेज API Felo मॉडल कैटलॉग के मॉडलों से इमेज बनाती और संपादित करती है। यह असिंक्रोनस है: सबमिट अनुरोध तुरंत task ID लौटाता है, और आप कार्य के टर्मिनल स्थिति तक पहुंचने तक उसे पोल करते हैं।

यह पेज इमेज-विशिष्ट अनुबंध बताता है। साझा कार्य जीवनचक्र के लिए Async Tasks देखें।

शुरू करने से पहले

• एक API key। Authentication देखें।
• ऐसा मॉडल जिसका 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 array की अपेक्षा करता है और कार्य पोल नहीं कर सकता। endpoint को HTTP से कॉल करें और कार्य पोल करें, या दोनों चरणों के लिए छोटा wrapper लिखें।

कार्य सबमिट करें

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 का अर्थ है कि प्लेटफ़ॉर्म ने कार्य स्वीकार किया। इसका अर्थ यह नहीं कि prompt, पैरामीटर या संदर्भ इमेज मान्य हैं। upstream कॉल प्रतिक्रिया के बाद चलती है, इसलिए अधिकतर अनुरोध समस्याएं बाद में विफल कार्य के रूप में दिखती हैं। अपवाद मॉडल रूटिंग है: chat या वीडियो मॉडल सबमिट पर अस्वीकार किया जाता है।

कार्य टर्मिनल होने तक पोल करें

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

कार्य विफलताएं HTTP स्टेटस को 200 पर रखती हैं। केवल HTTP स्टेटस नहीं, body में status जांचें।

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 पढ़ें और संग्रहित करें

जब कार्य सफल होता है, 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 key के डाउनलोड होता है, इसलिए इसे bearer लिंक मानें।
• URL समय-सीमित है। exp query पैरामीटर उसकी समाप्ति समय है। फ़ाइल डाउनलोड करें और उसे अपने bucket या फ़ाइलसिस्टम में रखें; कार्य स्थायी संग्रहण नहीं है।
• 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 में पास करें। मॉडल उन्हें कॉन्टेक्स्ट के रूप में उपयोग करता है; prompt अब भी बदलाव का वर्णन करता है।

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 है। संदर्भों का क्रम सुरक्षित रहता है; जब मायने रखे तो prompt में इमेज को उनकी स्थिति से संदर्भित करें। वर्तमान मॉडल 14 संदर्भों तक स्वीकार करते हैं।

अनुरोध फ़ील्ड

वर्तमान इमेज मॉडल:

किसी आपूर्तिकर्ता को पिन करने के लिए, मॉडल की channels सूची से चैनल कोड के साथ X-Felo-Channel हेडर भेजें। Channels and Provider Routing देखें।

इमेज मॉडल खोजें (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 दिखाता है। इमेज दरें token दरें हैं: resolution बदलता है कि एक इमेज कितने आउटपुट इमेज tokens लेती है, इसलिए 4K इमेज 1K इमेज से अधिक महंगी है। संदर्भ इमेज इनपुट इमेज tokens जोड़ती हैं।

कार्य प्रतिक्रिया में usage ऑब्जेक्ट शामिल नहीं होता। शुल्क के लिए Console Billing देखें।

failed या interrupted पर समाप्त होने वाला कार्य कोई आउटपुट नहीं देता और उसका बिल नहीं लगता। 402 के साथ अस्वीकृत सबमिट ने कार्य नहीं बनाया।

त्रुटियां

इमेज रूट की endpoint-स्तरीय त्रुटियां OpenAI error envelope का उपयोग करती हैं:

{
  "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 प्रतिक्रिया हेडर में होता है। इसे task ID के साथ लॉग करें।

प्रमाणीकरण त्रुटियां Errors, Limits, and Retries में बताई गई हैं।

संबंधित

• Async Tasks
• Models and Pricing
• Channels and Provider Routing
• Errors, Limits, and Retries