Görüntü oluşturma

Kunavo, /v1/images/generations (metinden görsel oluşturma) ve /v1/images/edits (görselden görsel üretme / düzenleme) uç noktalarını sunar. Her ikisi de varsayılan olarak eşzamanlı çalışır — çağrı, üst akış işlemi tamamlanana kadar bekler ve ardından sonuç URL'lerini döndürür — veya "async": true ya da bir webhook_url ile asenkron kullanın.

Metinden görsel oluşturma

Uç nokta: POST /v1/images/generations. OpenAI SDK'sının images.generate yöntemini kullanın veya doğrudan curl ile çağrı yapın.

img = client.images.generate(
    model="nano-banana-pro",
    prompt="a red origami crane on a white desk, soft window light",
    size="1024x1024",
)
print(img.data[0].url)

Yaygın parametreler

Çözünürlük katmanları

Bazı görsel modelleri, çıktı çözünürlüğüne göre kademeli ücretlendirir. Bir düzey seçmek için resolution gönderin; bu parametreyi göndermezseniz varsayılan düzey kullanılır. Ücret, gerçekte oluşturulan düzeye göre alınır.

veo-3 ailesinde de çözünürlüğe göre kademeli ücretlendirme uygulanır — her modelin /models sayfasında düzey başına ücretler yer alır.

Görsel düzenleme / görselden görsel üretme

Uç nokta: POST /v1/images/edits. Tek görsel düzenlemeleri için kaynak görseli URL (HTTPS veya data: base64) olarak image üzerinden, çoklu görsel referansları içinse image_urls üzerinden gönderin.

# Image edit / image-to-image: pass the source image URL
import requests

resp = requests.post(
    "https://api.kunavo.com/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2-edit",
        "prompt": "recolor the crane to bright blue, keep composition",
        "image": "https://your-cdn.com/source.png",
    },
)
print(resp.json()["data"][0]["url"])

Çoklu görsel referansı

Bazı modeller (Nano Banana Edit, GPT-Image-2 Edit) birden fazla referans görseli kabul eder.

# nano-banana-edit accepts multiple reference images
resp = requests.post(
    "https://api.kunavo.com/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "nano-banana-edit",
        "prompt": "merge subject from img1 with background from img2",
        "image_urls": [
            "https://your-cdn.com/subject.png",
            "https://your-cdn.com/background.png",
        ],
    },
)

Desteklenen düzenleme modelleri

• nano-banana-edit — Google Nano Banana görsel düzenleme
• gpt-image-2-edit — OpenAI görselden görsele

Kaynak görsel sağlama

Görsel düzenleme ve görselden videoya özellikleri, modelin erişebileceği bir kaynak görsel gerektirir. Üç seçeneğiniz var — uygulamanıza uygun olanı seçin:

• Zaten herkese açık bir URL'niz var — URL'yi doğrudan image (video için image_url) olarak gönderin. İşlem tamam.
• Yerel bir dosyanız var — dosyayı POST /v1/files üzerinden bir kez yükleyin ve döndürülen kalıcı URL'yi yeniden kullanın.
• Kodunuzda ham baytlar var — bunları data: base64 URI olarak satır içine ekleyin; Kunavo bunları sizin için barındırır.

Seçenek A — POST /v1/files üzerinden yükleme

Bir file alanıyla (veya JSON { "file": "data:..." } ile) multipart/form-data gönderin. Kalıcı bir files.kunavo.com URL'si alırsınız — dosyalar en fazla 25 MB olabilir.

# Upload a local file → get a permanent Kunavo URL
import requests

with open("source.png", "rb") as f:
    up = requests.post(
        "https://api.kunavo.com/v1/files",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
    ).json()

# up["url"] is now a permanent https://files.kunavo.com/... URL
edit = requests.post(
    "https://api.kunavo.com/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2-edit",
        "prompt": "recolor the crane to bright blue",
        "image": up["url"],
    },
).json()
print(edit["data"][0]["url"])

Seçenek B — base64'ü satır içine ekleme

Ayrı bir yükleme işlemini tamamen atlayın: image / image_url alanına bir data: URI'si koyun. Kunavo bunu çözümler, CDN'sinde barındırır ve barındırılan URL'yi modele iletir.

# Or skip the upload step — pass base64 inline, we host it for you.
import base64, requests

with open("source.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.kunavo.com/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2-edit",
        "prompt": "recolor the crane to bright blue",
        "image": f"data:image/png;base64,{b64}",
    },
)

Yanıt biçimi

Her iki uç nokta da OpenAI'nin standart görseller yanıtını döndürür:

{
  "created": 1779360636,
  "data": [
    { "url": "https://files.kunavo.com/image/.../result.png" }
  ]
}

Gecikme ve zaman aşımları

Görsel oluşturma, modele bağlı olarak genellikle 5–60 saniye sürer. Varsayılan eşzamanlı modda Kunavo bağlantıyı açık tutar ve 504 döndürmeden önce üst hizmeti en fazla 540 saniye boyunca düzenli aralıklarla sorgular. İstemci tarafındaki zaman aşımını buna göre ayarlayın — veya isteği saniyeler içinde gönderip kendi belirlediğiniz aralıklarla sorgulamak için asenkron API'yi kullanın:

• Nano Banana / Nano Banana 2: genellikle 10 saniyenin altında.
• Nano Banana Pro / GPT-Image-2: 15–60 saniye.
• Çoklu referans + üst düzey katman: yaklaşık 2 dakikaya kadar.

Asenkron API (gönderme + yoklama / web kancası)

Her iki görsel uç noktası da varsayılan olarak eşzamanlıdır — çağrı, üst akış görseli oluşturana kadar bağlantıyı açık tutar ve ardından standart OpenAI görseller yanıtını döndürür. Toplu işler, yavaş üst düzey katmanlar veya uzun bir isteği açık tutamayan sunucusuz istemciler için /v1/images/generations ya da /v1/images/edits öğesine "async": true (veya bir webhook_url) ekleyin.

Gönderme işlemi hemen bir img_* kimliği döndürür; GET /v1/images/{id} öğesini, status değeri completed veya failed olana kadar yoklayın — ya da bir web kancası kaydedip yoklama işlemini tamamen atlayın.

# Async: add "async": true (or a webhook_url) to either image endpoint.
# The call returns instantly with an img_ id instead of holding the connection.
import requests, time

API = "https://api.kunavo.com/v1"
H = {"Authorization": f"Bearer {API_KEY}"}

submit = requests.post(
    f"{API}/images/generations",
    headers=H,
    json={"model": "gpt-image-2", "prompt": "a red panda", "async": True},
).json()

task_id = submit["id"]        # "img_abc..."
status  = submit["status"]    # "queued"

# Poll GET /v1/images/{id} until terminal — or skip polling and use a webhook.
while status not in ("completed", "failed"):
    time.sleep(3)
    r = requests.get(f"{API}/images/{task_id}", headers=H).json()
    status = r["status"]

if status == "completed":
    print(r["output"]["url"])
else:
    print("failed:", r["error"])

Görev nesnesi

Web kancaları

Gönderme sırasında webhook_url (https) iletin; görev sona erdiğinde Kunavo imzalı bir image.completed / image.failed olayı için POST isteği gönderir — video ve müzik web kancalarıyla aynı zarf ve imza kullanılır:

• X-Kunavo-Webhook-Id — kararlı olay kimliği; yeniden denemelerde değişmez (yinelenenleri ayıklamak için kullanın).
• X-Kunavo-Webhook-Timestamp — imzanın hesaplandığı Unix zamanı, saniye cinsinden.
• X-Kunavo-Webhook-Signature — {timestamp}.{rawBody} üzerinden, web kancası gizli anahtarınızla hesaplanan sha256= HMAC-SHA256.

Ham girdi için geçiş seçeneği

Kunavo'nun eşlemediği model başına parametreler (seed, negatif istem, çıktı biçimi) için input gönderin. Bu değer, bağdaştırıcımızın oluşturacağı girdinin yerine, olduğu gibi üst akışa gönderilir.

Modelin fiyat düzeyini seçen alan istisnadır: resolution, Ideogram'da ise rendering_speed. Düzeyleri olan bir modelde bu alan her zaman modelin düzeylerinden biri olarak gönderilir ve ücret bu düzeye göre alınır. input bu alanı içermiyorsa veya modelin düzeylerinden biri olmayan bir değer veriyorsa varsayılan düzey gönderilir ve ücret buna göre alınır. input ayarlandığında, isteğin en üst seviyesindeki aynı alan okunmaz.

# Raw upstream 'input': sent as written, in place of what our adapter builds.
# "resolution" sets the billed tier: 2K here, the default tier when left out.
resp = client.images.generate(
    model="nano-banana-2",
    prompt="",  # ignored when input is set
    extra_body={"input": {
        "prompt": "a futuristic cyberpunk skyline at dusk",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "output_format": "png",
    }},
)

Sonraki adımlar

• Tüm görsel modellerine fiyatlarıyla göz atın
• Görsel fiyatlandırması nasıl işler?