POST /v1/images/

GPT Image modelleriyle görüntü üretmek veya referanslara göre görüntü düzenlemek için OpenAI Images uyumlu bir API. Kullanım büyük ölçüde OpenAI SDK ile aynıdır: base_url'yi 4AICode'a yönlendirin ve api_key'yi sk-4ai-... token'ınızla değiştirin.

Görüntü üretimi cüzdan bakiyenize karşı istek başına ücretlendirilir. Konsoldaki Görüntü üretimi sayfası manuel kullanım için uygundur; API ise kendi uygulamalarınıza, iş akışlarınıza ve otomasyon betiklerinize entegrasyon için tasarlanmıştır.

Yeni projeler için GPT Image 2.5 tercih edin: gpt-image-2.5-sunburst yüksek kaliteli üretim ve hassas düzenleme için en yetenekli seçenektir; gpt-image-2.5-flare yüksek kaliteli günlük görüntü üretimi için en hızlı seçimdir. Mevcut entegrasyonlar gpt-image-2 kullanmaya devam edebilir.

Uç noktalar

POST https://relay.4aicode.com/v1/images/generations
POST https://relay.4aicode.com/v1/images/edits

Desteklenen modeller

Model	Kullanım durumu	Faturalama
`gpt-image-2.5-sunburst`	Yüksek kaliteli üretim ve hassas düzenleme için en yetenekli GPT Image 2.5 modeli	Cüzdan bakiyenize karşı istek başına ücretlendirilir
`gpt-image-2.5-flare`	Yüksek kaliteli günlük görüntü üretimi için hızlı GPT Image 2.5 modeli	Cüzdan bakiyenize karşı istek başına ücretlendirilir
`gpt-image-2`	Metinden görüntü üretimi ve referans tabanlı görüntü düzenleme	Cüzdan bakiyenize karşı istek başına ücretlendirilir

Her model, bir yönetici kullanım başına fiyatını yapılandırıp etkinleştirdikten ve bir üst model listesinde seçtikten sonra kullanılabilir. Model etkin değilse API 503 model_unavailable döner.

Metinden görüntü üretimi

curl

curl https://relay.4aicode.com/v1/images/generations \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A clean product shot of a black mechanical keyboard on a white desk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

Python

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A clean product shot of a black mechanical keyboard on a white desk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)

image_base64 = resp.data[0].b64_json
with open("keyboard.png", "wb") as f:
    f.write(base64.b64decode(image_base64))

TypeScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A clean product shot of a black mechanical keyboard on a white desk",
  size: "1024x1024",
  quality: "medium",
  response_format: "b64_json",
});

const image = resp.data[0]?.b64_json;
if (!image) throw new Error("image generation failed");
fs.writeFileSync("keyboard.png", Buffer.from(image, "base64"));

Referans tabanlı görüntü düzenleme

/v1/images/edits iki giriş yöntemini destekler:

multipart/form-data: image veya image[] alanıyla dosya yükleyin. Her dosyanın maksimum boyutu 20 MB'tır.
application/json: images[].image_url içinde bir base64 data URL veya erişilebilir bir görüntü URL'si geçirin.

multipart curl

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Keep the product, replace the background with a bright studio setup" \
  -F size="1024x1024" \
  -F quality="medium" \
  -F response_format="b64_json" \
  -F image="@./product.png"

Birden fazla referans görüntü:

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Combine these references into one cohesive hero image" \
  -F image[]="@./subject.png" \
  -F image[]="@./style.png"

JSON Data URL

IMAGE_B64="$(base64 < product.png | tr -d '\n')"

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-image-2.5-sunburst\",
    \"prompt\": \"Put this product in a premium ecommerce scene\",
    \"size\": \"1024x1024\",
    \"quality\": \"medium\",
    \"response_format\": \"b64_json\",
    \"images\": [
      { \"image_url\": \"data:image/png;base64,${IMAGE_B64}\" }
    ]
  }"

file_id şu anda açık bir hata döner. Maske kullanmak için mask dosya alanı üzerinden sağlayın veya JSON'da mask.image_url geçirin.

Parametreler

Parametre	Uygulanabilir uç noktalar	Açıklama
`model`	Tümü	Yukarıdaki tablodan etkin bir model ID
`prompt`	Tümü	Zorunlu üretim veya düzenleme talimatları
`size`	Tümü	`auto`, `1024x1024`, `1536x1024` veya `1024x1536`
`quality`	Tümü	`auto`, `low`, `medium` veya `high`; GPT Image 2.5 ayrıca `xhigh` ve `max` destekler
`response_format`	Tümü	`b64_json` veya `url`; `url` bir data URL döner
`output_format`	Tümü	`png`, `jpeg` veya `webp`
`background`	Tümü	Üst görüntü aracına iletilir
`output_compression`	Tümü	Sıkıştırmayı destekleyen formatlar için çıkış sıkıştırma oranı
`stream`	Tümü	`true` olduğunda SSE döner
`partial_images`	Tümü	Akış modunda kısmi görüntü olayları ister
`image` / `image[]`	edits	Multipart ile sağlanan referans görüntüler
`images[].image_url`	edits	JSON ile sağlanan referans görüntü URL'si veya data URL
`mask` / `mask.image_url`	edits	İsteğe bağlı maske
`input_fidelity`	edits	Referans görüntü sadakati, üst görüntü aracına iletilir

Yanıt

Akışsız istekler OpenAI Images tarzı bir yanıt döner:

{
  "created": 1770000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "usage": {
    "images": 1
  }
}

response_format=url olduğunda data[].url bir data:image/png;base64,... URL'si içerir; görüntü içeriği doğrudan yanıtta döner.

Akışlı yanıtlar

"stream": true ayarlayarak SSE döndürün.

Metinden görüntü üretim olayları:

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"..."}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","usage":{"images":1}}

Referans tabanlı görüntü düzenleme olayları image_edit önekini kullanır:

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"images":1}}

Faturalama ve kayıtlar

Her başarılı üretim, seçilen modelin güncel istek başına fiyatı üzerinden ücretlendirilir. Kullanım sayfası, cüzdan işlem geçmişi ve backend kullanım günlüğü modeli, istek sayısını, maliyeti, durumu ve izleme kimliğini kaydeder. Platform varsayılan olarak istemlerinizi veya görüntü içeriğinizi saklamaz.

Yaygın hatalar

HTTP	code	Çözüm
400	`invalid_request_error`	`prompt`, `model`, görüntü alanları ve multipart biçimlendirmesini kontrol edin
401	`unauthorized`	`Authorization: Bearer sk-4ai-...` kontrol edin
429	`insufficient_quota` / `rate_limit`	Cüzdanınıza bakiye ekleyin veya eşzamanlılığı azaltın
503	`model_unavailable`	Seçilen görüntü modeli için istek başına fiyatlandırmayı etkinleştirmek üzere bir yöneticiyle iletişime geçin
502	`upstream_error`	Daha sonra yeniden deneyin; sorun sürerse izleme kimliğiyle desteğe başvurun