Generování obrázků

API Felo pro obrázky generuje a upravuje obrázky pomocí modelů z katalogu modelů Felo. Je asynchronní: požadavek na odeslání okamžitě vrací ID úlohy a vy se na úlohu dotazujete, dokud nedosáhne koncového stavu.

Tato stránka pokrývá kontrakt specifický pro obrázky. Společný životní cyklus úloh najdete v části Asynchronní úlohy.

Než začnete

• API klíč. Viz Ověřování.
• Model, jehož model_kind je image_generation. Viz Najít model pro obrázky.
• Základní URL https://openapi.felo.ai.

Jak se liší od OpenAI Images API

Cesta je podobná OpenAI Images API. Odpověď nikoli:

Neodesílejte openai.images.generate() na tento endpoint. SDK očekává synchronní pole data a nedokáže dotazovat úlohu. Volejte endpoint přes HTTP a dotazujte úlohu, nebo napište malý obal pro oba kroky.

Odešlete úlohu

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

Úspěšné odeslání vrací HTTP 202:

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

202 znamená, že platforma úlohu přijala. Neznamená to, že prompt, parametry nebo referenční obrázky jsou platné. Volání upstreamu proběhne po odpovědi, takže většina problémů s požadavkem se objeví později jako neúspěšná úloha. Výjimkou je směrování modelu: chatový nebo video model je odmítnut při odeslání.

Dotazujte se, dokud úloha nedosáhne koncového stavu

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

Selhání úlohy zachovává stav HTTP 200. Zkontrolujte status v těle, nejen stav HTTP.

Začněte intervalem 2–5 sekund a zvyšujte jej. Většina obrázků se dokončí do minuty; výstup 4K a úpravy s mnoha referenčními obrázky trvají déle. Vždy si nastavte vlastní časový limit.

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

Přečtěte a uložte výstupy

Když úloha uspěje, outputs obsahuje jednu položku na vygenerovaný obrázek:

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

• outputs je prázdné, dokud úloha neuspěje.
• url je podepsaná URL. Stahuje se bez API klíče, proto s ní zacházejte jako s nosným odkazem.
• URL je časově omezená. Parametr dotazu exp je její čas expirace. Stáhněte soubor a uložte jej do vlastního bucketu nebo souborového systému; úloha není trvalé úložiště.
• Opětovné dotazování po expiraci URL vrací stejnou expirovanou URL. Nevydává novou.
• Odpověď neobsahuje obrazová data 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)

Upravte obrázek

Předejte referenční obrázky v poli input_references. Model je použije jako kontext; prompt stále popisuje změnu.

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

Každá reference je URL protokolu HTTP(S) nebo datová URL base64. Pořadí referencí je zachováno; pokud na tom záleží, odkazujte na obrázky v promptu podle pozice. Současné modely přijímají až 14 referencí.

Pole požadavku

Současné obrazové modely:

Chcete-li připnout poskytovatele, odešlete hlavičku X-Felo-Channel s kódem kanálu ze seznamu channels modelu. Viz Kanály a směrování poskytovatelů.

Najít model pro obrázky

Neexistuje samostatný seznamový endpoint obrazových modelů. Dotazujte se na obecný katalog a filtrujte podle 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} vrací kanály modelu a publikované sazby.

supported_parameters v obecném katalogu je seznam na úrovni protokolu. U obrazových modelů spolehlivě nevyjmenovává výše uvedená obrazová pole, proto z něj nesestavujte svůj požadavek. Použijte tabulku polí v této příručce a ID modelu potvrďte v katalogu.

Ceny

Generování obrázků se účtuje podle publikovaných sazeb modelu. Katalog zpřístupňuje input_image a output_image vedle textových sazeb prompt a completion. Obrazové sazby jsou tokenové sazby: resolution mění, kolik výstupních obrazových tokenů obrázek spotřebuje, takže obrázek 4K stojí více než obrázek 1K. Referenční obrázky přidávají vstupní obrazové tokeny.

Odpověď úlohy neobsahuje objekt usage. Účtovanou částku zkontrolujte v Console Billing.

Úloha, která skončí jako failed nebo interrupted, neprodukuje žádný výstup a neúčtuje se. Odeslání odmítnuté s 402 nevytvořilo úlohu.

Chyby

Chyby na úrovni endpointu z obrazové trasy používají obálku chyb OpenAI:

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

ID požadavku je v hlavičce odpovědi X-Request-Id. Zaznamenejte jej spolu s ID úlohy.

Chyby ověřování jsou popsány v části Chyby, limity a opakování.

Související

• Asynchronní úlohy
• Modely a ceny
• Kanály a směrování poskytovatelů
• Chyby, limity a opakování