Penjanaan imej

API imej Felo menjana dan menyunting imej dengan model daripada katalog model Felo. Ia tak segerak: permintaan hantar mengembalikan ID tugasan dengan segera, dan anda meninjau tugasan sehingga ia mencapai keadaan terminal.

Halaman ini merangkumi kontrak khusus imej. Untuk kitaran hayat tugasan yang dikongsi, lihat Tugasan Tak Segerak.

Sebelum anda bermula

• Kunci API. Lihat Pengesahan.
• Model yang model_kind-nya ialah image_generation. Lihat Cari model imej.
• URL asas https://openapi.felo.ai.

Perbezaannya daripada API OpenAI Images

Laluannya serupa dengan API Images OpenAI. Responsnya tidak:

Jangan hantar openai.images.generate() ke endpoint ini. SDK menjangkakan tatasusunan data segerak dan tidak boleh meninjau tugasan. Panggil endpoint melalui HTTP dan tinjau tugasan, atau tulis pembalut kecil untuk kedua-dua langkah.

Hantar tugasan

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

Hantaran yang berjaya mengembalikan HTTP 202:

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

202 bermaksud platform menerima tugasan. Ia tidak bermaksud gesaan, parameter, atau imej rujukan itu sah. Panggilan huluan berjalan selepas respons, jadi kebanyakan masalah permintaan muncul kemudian sebagai tugasan yang gagal. Pengecualiannya ialah penghalaan model: model chat atau video ditolak semasa hantar.

Tinjau sehingga tugasan terminal

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

Kegagalan tugasan mengekalkan status HTTP pada 200. Semak status dalam badan, bukan hanya status HTTP.

Mulakan dengan selang 2–5 saat dan berundur. Kebanyakan imej selesai dalam masa seminit; output 4K dan suntingan dengan banyak imej rujukan mengambil masa lebih lama. Sentiasa tetapkan had masa anda sendiri.

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

Baca dan simpan output

Apabila tugasan berjaya, outputs mengandungi satu entri setiap imej yang dijana:

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

• outputs kosong sehingga tugasan berjaya.
• url ialah URL bertandatangan. Ia dimuat turun tanpa kunci API, jadi perlakukan ia sebagai pautan pembawa.
• URL terhad masa. Parameter pertanyaan exp ialah masa tamat tempohnya. Muat turun fail dan simpan dalam baldi atau sistem fail anda sendiri; tugasan bukan storan kekal.
• Meninjau semula selepas URL tamat tempoh mengembalikan URL tamat tempoh yang sama. Ia tidak mengeluarkan URL baharu.
• Respons tidak termasuk data imej 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)

Sunting imej

Hantar imej rujukan dalam input_references. Model menggunakannya sebagai konteks; gesaan masih menerangkan perubahan.

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

Setiap rujukan ialah URL HTTP(S) atau URL data base64. Susunan rujukan dikekalkan; rujuk imej mengikut kedudukan dalam gesaan apabila ia penting. Model semasa menerima sehingga 14 rujukan.

Medan permintaan

Model imej semasa:

Untuk menetapkan pembekal, hantar pengepala X-Felo-Channel dengan kod saluran daripada senarai channels model. Lihat Saluran dan Penghalaan Penyedia.

Cari model imej

Tiada endpoint senarai model imej berasingan. Pertanyaan katalog umum dan tapis mengikut 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} mengembalikan saluran model dan kadar yang diterbitkan.

supported_parameters dalam katalog umum ialah senarai peringkat protokol. Untuk model imej, ia tidak menyenaraikan medan imej di atas dengan boleh dipercayai, jadi jangan bina permintaan anda daripadanya. Gunakan jadual medan dalam panduan ini dan sahkan ID model daripada katalog.

Harga

Penjanaan imej dibilkan daripada kadar yang diterbitkan model. Katalog mendedahkan input_image dan output_image bersama kadar teks prompt dan completion. Kadar imej ialah kadar token: resolution mengubah bilangan token imej output yang digunakan oleh sesuatu imej, jadi imej 4K lebih mahal daripada imej 1K. Imej rujukan menambah token imej input.

Respons tugasan tidak termasuk objek usage. Semak Console Billing untuk caj.

Tugasan yang berakhir failed atau interrupted tidak menghasilkan output dan tidak dibilkan. Hantaran yang ditolak dengan 402 tidak mencipta tugasan.

Ralat

Ralat peringkat endpoint daripada laluan imej menggunakan sampul ralat OpenAI:

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

ID permintaan berada dalam pengepala respons X-Request-Id. Log ia bersama ID tugasan.

Ralat pengesahan diterangkan dalam Ralat, Had, dan Cuba Semula.

Berkaitan

• Tugasan Tak Segerak
• Model dan Harga
• Saluran dan Penghalaan Penyedia
• Ralat, Had, dan Cuba Semula