Görsel üretimi

Felo görsel API'si, Felo model kataloğundaki modellerle görsel oluşturur ve düzenler. Eşzamansızdır: gönderme isteği hemen bir görev kimliği döndürür ve siz görev nihai bir duruma ulaşana kadar yoklarsınız.

Bu sayfa görsele özgü sözleşmeyi kapsar. Paylaşılan görev yaşam döngüsü için bkz. Eşzamansız Görevler.

Başlamadan önce

• Bir API anahtarı. Bkz. Kimlik Doğrulama.
• model_kind değeri image_generation olan bir model. Bkz. Görsel modeli bulma.
• https://openapi.felo.ai temel URL'si.

OpenAI Images API'den farkı

Yol, OpenAI'nin Images API'sine benzer. Yanıt benzemez:

openai.images.generate() çağrısını bu endpoint'e göndermeyin. SDK eşzamanlı bir data dizisi bekler ve bir görevi yoklayamaz. Endpoint'i HTTP üzerinden çağırıp görevi yoklayın veya iki adım için küçük bir sarmalayıcı yazın.

Görev gönderme

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"
  }'

Başarılı bir gönderme HTTP 202 döndürür:

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

202, platformun görevi kabul ettiği anlamına gelir. İstemin, parametrelerin veya referans görsellerinin geçerli olduğu anlamına gelmez. Upstream çağrısı yanıttan sonra çalışır, bu nedenle çoğu istek sorunu daha sonra başarısız bir görev olarak ortaya çıkar. İstisna model yönlendirmedir: bir sohbet veya video modeli gönderme sırasında reddedilir.

Görev nihai olana kadar yoklama

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

Görev arızaları HTTP durumunu 200 olarak tutar. Yalnızca HTTP durumunu değil, gövdedeki status alanını da kontrol edin.

2–5 saniyelik bir aralıkla başlayın ve geri çekilin. Çoğu görsel bir dakika içinde tamamlanır; 4K çıktı ve çok sayıda referans görselli düzenlemeler daha uzun sürer. Her zaman kendi son tarihinizi belirleyin.

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")

Çıktıları okuma ve saklama

Görev başarılı olduğunda outputs, oluşturulan her görsel için bir girdi içerir:

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

• outputs, görev başarılı olana kadar boştur.
• url imzalı bir URL'dir. API anahtarı olmadan indirilir, bu nedenle ona bearer bağlantı olarak davranın.
• URL zamanla sınırlıdır. exp sorgu parametresi sona erme zamanıdır. Dosyayı indirin ve kendi paketinizde veya dosya sisteminizde saklayın; görev kalıcı depolama değildir.
• URL'nin süresi dolduktan sonra yeniden yoklamak aynı süresi dolmuş URL'yi döndürür. Yeni bir URL vermez.
• Yanıt base64 görsel verisi içermez.

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)

Görsel düzenleme

Referans görsellerini input_references içinde geçirin. Model bunları bağlam olarak kullanır; istem yine değişikliği açıklar.

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"}
      }
    ]
  }'

Her referans bir HTTP(S) URL'si veya bir base64 veri URL'sidir. Referans sırası korunur; önemli olduğunda istemde görsellere konumlarıyla atıfta bulunun. Mevcut modeller 14 adede kadar referans kabul eder.

İstek alanları

Mevcut görsel modelleri:

Bir sağlayıcıyı sabitlemek için modelin channels listesinden bir kanal koduyla X-Felo-Channel başlığını gönderin. Bkz. Kanallar ve Sağlayıcı Yönlendirme.

Görsel modeli bulma

Ayrı bir görsel modeli listeleme endpoint'i yoktur. Genel kataloğu sorgulayın ve model_kind ile filtreleyin:

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} modelin kanallarını ve yayımlanmış ücretlerini döndürür.

Genel katalogdaki supported_parameters protokol düzeyinde bir listedir. Görsel modelleri için yukarıdaki görsel alanlarını güvenilir şekilde numaralandırmaz, bu nedenle isteğinizi ondan oluşturmayın. Bu kılavuzdaki alan tablosunu kullanın ve model kimliğini katalogdan doğrulayın.

Fiyatlandırma

Görsel oluşturma, modelin yayımlanmış ücretlerinden faturalandırılır. Katalog, metin prompt ve completion ücretlerinin yanında input_image ve output_image sunar. Görsel ücretleri token ücretleridir: resolution, bir görselin kaç çıkış görsel token'ı tükettiğini değiştirir, bu nedenle 4K bir görsel 1K bir görselden daha pahalıdır. Referans görselleri giriş görsel token'ları ekler.

Görev yanıtı bir usage nesnesi içermez. Ücret için Console Billing'i kontrol edin.

failed veya interrupted ile biten bir görev çıktı üretmez ve faturalandırılmaz. 402 ile reddedilen bir gönderme görev oluşturmadı.

Hatalar

Görsel rotasından gelen endpoint düzeyindeki hatalar OpenAI hata zarfını kullanır:

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

İstek kimliği X-Request-Id yanıt başlığındadır. Bunu görev kimliğiyle birlikte günlüğe kaydedin.

Kimlik doğrulama hataları Hatalar, Sınırlar ve Yeniden Denemeler bölümünde açıklanmıştır.

İlgili

• Eşzamansız Görevler
• Modeller ve Fiyatlar
• Kanallar ve Sağlayıcı Yönlendirme
• Hatalar, Sınırlar ve Yeniden Denemeler