JoyAI Image API

API Dokümantasyonu

Tek bir genel API ile görsel oluşturun ve düzenleyin. joyai ile talimat tabanlı düzenleme veya gptimage2 ile GPT Image 2 metin-görsel ve düzenleme.

API Anahtarlarını Yönet Hızlı Başlangıç

Genel Bakış

Uç Nokta

/api/v1/generate

Desteklenen görsel modelleri için tek uç nokta. model alanıyla davranış seçin.

Auth

Bearer API anahtarları

Authorization başlığında panel API anahtarı kullanın. Sunucu anahtarları tarayıcıya gönderilmez.

Async

Görev tabanlı sonuçlar

Oluşturma bir task ID döndürür. Nihai URL'ler için status'u yoklayın.

Kimlik Doğrulama

Her istek Authorization başlığında API anahtarı gerektirir. Anahtarları şuradan oluşturun veya yenileyin: Panel > API Anahtarları.

Başlık

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modeller ve Krediler

model	En uygun	Görsel girişi gerekli	Krediler
`joyai`	1–3 referans görselle talimat tabanlı düzenleme.	Evet, 1–3 görsel URL.	İstek başına 24 kredi.
`gptimage2`	GPT Image 2 metin-görsel ve düzenleme.	İsteğe bağlı. Düzenleme modu için görsel ekleyin.	Text: 1k/2k/4k için low 2/4/6, medium 12/24/36, high 44/88/132. Edit: low 6/12/18, medium 12/24/36, high 44/88/132.

Hızlı Başlangıç

Şu adrese istek gönderin: POST /api/v1/generate. adresine istek gönderin. API hemen task ID döndürür; GET /api/v1/status ile başarı veya hata olana kadar yoklayın.

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

Görsel oluşturma veya düzenleme görevi oluşturur. İstek gövdesi JSON.

İstek Parametreleri

Ad	Tür	Gerekli	Açıklama
`model`	string	Evet	joyai veya gptimage2 kullanın.
`prompt`	string	Evet	Doğal dil talimatı. joyai en fazla 1500 karakter; gptimage2 en fazla 20000.
`images`	string[]	joyai için gerekli; gptimage2 için isteğe bağlı	Görsel URL'leri. joyai 1–3 kabul eder; gptimage2 görsel varsa düzenleme moduna geçer.
`size`	string	joyai için isteğe bağlı	10241024 gibi çıktı boyutu. Varsayılan 10241024.
`quality`	string	gptimage2 için isteğe bağlı	low, medium veya high. Varsayılan medium.
`resolution`	string	gptimage2 için isteğe bağlı	1k, 2k veya 4k. Varsayılan 1k.
`aspect_ratio`	string	gptimage2 için isteğe bağlı	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 veya 21:9.
`output_format`	string	gptimage2 için isteğe bağlı	png, jpeg veya webp. Varsayılan png.
`callback_url`	string	İsteğe bağlı	Görevle birlikte saklanabilen callback URL'si.

JoyAI Düzenleme Örneği

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

GPT Image 2 Örneği

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

Yanıt

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

Durumu şu uç noktanın döndürdüğü task ID ile yoklayın: /api/v1/generate. tarafından döndürülen task ID ile durumu yoklayın. model isteğe bağlıdır; mümkünse task ID'ler otomatik yönlendirilir.

cURL

curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

Hatalar

Hatalar başarılı yanıtlarla aynı zarfı kullanır. Genel yanıtlar dahili sağlayıcı, worker veya yönlendirme ayrıntılarını göstermez.

JSON

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}

Durum	Anlam
`400`	Eksik veya geçersiz parametreler.
`401`	Eksik veya geçersiz API anahtarı.
`402`	Yetersiz kredi.
`500`	Oluşturma servisi veya sunucu hatası. Tekrarlanırsa destekle iletişime geçin.