Seedream 5.0 Pro API

Yetenekler

Fiyatlandırma ve krediler

Aşağıdaki fiyatlar döndürülen görsel başına geçerlidir. Normal görsel oluşturma işlemi bir görsel için kredi rezerve eder. Katmanlara ayırma işlemi ise 17 görsel için kredi rezerve eder, fiilen döndürülen görsel sayısı (ana görsel dahil) üzerinden ücretlendirilir ve kullanılmayan kredileri alındıkları bakiyeye iade eder. Başarısız olan görevlerin ücreti tamamen iade edilir.

Varsayılan 2K çözünürlükte, katmanlara ayırma işlemi 136 kredi rezerve eder. Dört görsel döndürülürse, nihai ücret 32 kredi olur ve kalan 104 kredi iade edilir.

İsteklerde aynı işlemin tekrar ücretlendirilmesini önleyen idempotency desteği yoktur. Her geçerli POST isteği, ücretlendirilebilir yeni bir görev oluşturur. Gönderim sonucunun belirsiz olduğu durumlarda, dönen taskId değerini sorgulayın; POST isteğinin yeniden denenmesi başka bir görev oluşturabilir.

Kimlik doğrulama

Panelde bir API anahtarı oluşturun. Anahtarın tamamı yalnızca bir kez gösterilir. Bu anahtarı sunucunuzda saklayın ve her istekte Bearer token olarak gönderin.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Bu örnekleri çalıştırmadan önce SEEVIO_API_KEY ortam değişkenini tanımlayın. JavaScript örnekleri sunucunuzda Node.js ile çalışır; Python örnekleri ise requests paketini kullanır.

İstek gövdesi

Giriş parametreleri

Her istek bir görev oluşturur. Metinden görsele ve görselden görsele modelleri tek bir görsel döndürür; katman ayrıştırma (layer-decomposition) ise ana görsel dahil olmak üzere 1 ila 17 arasında görsel döndürür. Katman ayrıştırma için aspect_ratio parametresini göndermeyin.

Hızlı başlangıç

Bu temel isteği gönderin, dönen taskId değerini kaydedin ve ardından aşağıdaki görev sorgulama örneğini kullanın. İstek oluşturma yanıtındaki credits değeri, ayrılan (rezerve edilen) miktarı gösterir.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Görev oluşturma yanıtı örneği

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

Metinden görsele

Seevio API anahtarınızla görseller oluşturun, referansları düzenleyin veya bir görseli katmanlarına ayırın. Görevler asenkron olarak çalışır; taskId değerini kaydedip durum sorgulama uç noktasını kullanabilir veya bir geri çağırma alabilirsiniz.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Görselden görsele

Görsel düzenleme için generation_type parametresini image-to-image olarak ayarlayın ve image_urls değerlerini sağlayın. Diğer tüm parametreler aynı kurallara tabidir.

example.com medya URL'lerini kendi genel erişime açık HTTPS dosyalarınızla değiştirin. Örnek URL'ler istek yapısını göstermek amaçlıdır ve indirilebilir örnek varlıklar değildir.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Katmanlara ayırma

generation_type değerini layer-decomposition olarak ayarlayın ve tam olarak bir adet görsel URL'si belirtin. aspect_ratio parametresini atlayın. output_format yalnızca ana görselin biçimini kontrol eder. Ayrıştırılan katmanlar her zaman şeffaflığı koruyacak şekilde PNG formatında döndürülür. data.results alanında döndürülen her URL'yi kaydedin.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

Katmanlara ayırma işlemi data.results altında birden fazla görsel URL'si döndürebilir: ana görsel ve ayrıştırılmış katmanlar. Her URL ayrı bir görseli gösterir. Sonuç sayısı göreve göre değişir (toplamda 1-17 görsel); yalnızca data.results[0] elemanını değil, tüm diziyi işleyin. Tamamlanan görev sorgusu ve tamamlama webhook'u bu diziyi içerir. İlk oluşturma yanıtı görsel URL'lerini değil, taskId ve rezerve edilen kredileri içerir.

Görev oluşturma yanıtı örneği

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

Tamamlanmış katmanlara ayırma: çoklu görsel URL'leri

Bu örnek yanıt, biri ana görsel ve üçü katman olmak üzere dört çıkış görselini göstermektedir. Sizin görevinizde dönen görsel sayısı farklı olabilir. Talep edilen 2K çözünürlükte credits, dört görselin tamamı için tahsil edilen nihai ücrettir; başlangıçtaki 17 görsellik rezervasyonun kullanılmayan kısmı iade edilmiştir.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Döndürülen her görseli işleyin

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

Görev sorgula

Örnek kimliği, oluşturma sırasında dönen taskId ile değiştirin. Sorgular yalnızca API anahtarının sahibine ait görevleri döndürür; erişilemeyen veya bilinmeyen kimlikler HTTP 404 döndürür.

Başlangıçta her 10-20 saniyede bir sorgulama yapın, HTTP 429 hatasında sıklığı azaltın ve durum completed veya failed olduğunda sorgulamayı durdurun. Üretim ortamında webhook'ları tercih edin. Aşağıdaki her kod örneği tek bir sorgu gerçekleştirir.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Sırada

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Tamamlandı

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Başarısız

Sorgu status=failed değerini döndürdüğünde üretim süreci başarısızlıkla sonuçlanmış demektir. Hatanın nedenini öğrenmek için failed_reason alanını, iade sonucunu görmek için ise billing_status alanını inceleyebilirsiniz. Bu örnekteki refunded ifadesi, kredilerin iade edildiğini gösterir. credits alanı orijinal rezerve edilen miktarı korur ve yanıt data alanını içermez.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Sonuç bağlantıları, depolamadan sonraki 30 gün boyunca kullanılabilir. Süre dolduktan sonra results alanı boş döner.

Webhook'lar

Görev tamamlandığında veya başarısız olduğunda bir JSON POST isteği almak için oluşturma isteğinde callback_url alanını ayarlayın. 15 saniye içinde bir 2xx yanıtı döndürün. İletilemeyen bildirimler tekrar denenir; yinelenen bildirimleri görev kimliğine göre tekilleştirerek (idempotent) işleyin.

Geri arama (callback) uç noktanız, JSON istek gövdesine (Content-Type: application/json) sahip POST isteklerini kabul etmelidir.

Geri çağırma (callback) ile görev oluşturma

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Geri çağırmalar (callbacks) görev sorgulama yanıt yapısını kullanır; iadeyle sonuçlanan başarısızlık bildirimleri ayrıca üst düzeyde credits_refunded bilgisini içerir. Görevi tanımlamak için id, tamamlananları başarısız olanlardan ayırt etmek için ise status değerini kullanın. Bildirimler tekrarlanabilir: Bunları id ve status değerlerine göre mükerrerliği önleyecek şekilde (idempotent) işleyin. Geri çağırmalar imzasızdır; görevi doğrulamak için kimliği doğrulanmış sorgu uç noktasını kullanın. Gönderim hatası, başarıyla tamamlanan bir görevin ücret iadesini tetiklemez.

Görev tamamlandı: Başarılı geri arama yükü

created_at olayın, task_created_at görevin oluşturulma zamanıdır; ikisi de Unix saniyesidir. Örnekler önerilen alanları gösterir; yanıtlar ek alanlar içerebilir.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Görev başarısız oldu: Başarısızlık geri arama yükü

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

Alıcı örneği

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Bu Next.js örneği, JSON geri arama gövdesini okur ve tamamlanan ya da başarısız olan görevleri doğrudan işler. Kendi uygulamanız için veri kalıcılığı ve görev kimliği (task-ID) tekilleştirme özellikleri ekleyin; geri aramayı onaylamadan önce yavaş çalışan işlemleri sıraya alın.

Hatalar

HTTP hataları, code ve message içeren bir error nesnesine sahiptir. Başarıyla kabul edilen bir görev daha sonra yine de başarısız olabilir; görevi sorgulayın veya başarısızlık geri çağırmasını işleyin.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Hatalar error.code ve error.message kullanır: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. 402 insufficient_credits hatası, mevcut kredilerinizin bu istek için yetersiz olduğu anlamına gelir.

İstek sınırları

Görev oluşturma: Her bir API anahtarı, varsayılan olarak dakikada en fazla 100 isteğe izin verir. Özel istek limitleri şu anda desteklenmemektedir.

Görev sorgulama: Her bir API anahtarı, varsayılan olarak dakikada en fazla 120 isteğe izin verir. Sorgulama istekleri ve görev oluşturma istekleri birbirinden bağımsız olarak sayılır.

Görsel ve video oluşturma istekleri aynı API anahtarı istek sınırını (rate limit) paylaşır.

HTTP 429 hatası, oluşturma için Retry-After: 60 ve sorgular için Retry-After: 5 başlıklarını içerir. Geri çekilme (backoff) yöntemini kullanın ve gereğinden daha sık sorgulama yapmaktan kaçının.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}