Seedream 5.0 Pro API

Schopnosti a funkce

Ceny a kredity

Ceny níže jsou uvedeny za jeden vrácený obrázek. Běžné generování rezervuje jeden obrázek. Rozklad na vrstvy rezervuje 17 obrázků, vyúčtuje skutečně vrácený počet (včetně základního obrázku) a nepoužité kredity vrátí na váš původní zůstatek. Selhané úlohy jsou plně refundovány.

Při výchozím rozlišení 2K je počet kreditů rezervovaných pro rozklad na vrstvy 136. Pokud se vrátí čtyři obrázky, konečná cena v kreditech je 32 a vrácená částka je 104.

Idempotence požadavků není podporována. Každý platný požadavek POST vytvoří novou zpoplatněnou úlohu. Pokud je výsledek odeslání nejistý, ověřte stav pomocí vráceného taskId; opakování požadavku POST může vytvořit další úlohu.

Ověření

Vytvořte si API klíč v administraci. Celý klíč se zobrazí pouze jednou. Uložte si ho na svém serveru a posílejte ho jako Bearer token v každém požadavku.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Před spuštěním těchto příkladů nastavte proměnnou prostředí SEEVIO_API_KEY. Příklady v JavaScriptu běží na vašem serveru v prostředí Node.js; příklady v Pythonu používají knihovnu requests.

Tělo požadavku

Vstupní parametry

Každý požadavek vytvoří jednu úlohu. Text-to-image a image-to-image vrací jeden obrázek; layer-decomposition vrací 1 až 17 obrázků včetně základního obrázku. Pro funkci layer-decomposition neposílejte parametr aspect_ratio.

Rychlý start

Odešlete tento minimální požadavek, uložte si vrácené taskId a poté použijte níže uvedený příklad dotazu na stav úlohy. Hodnota credits v odpovědi na vytvoření představuje rezervovanou částku.

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

Příklad odpovědi při vytvoření úlohy

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

Text na obrázek

Generujte obrázky, upravujte referenční předlohy nebo rozkládejte obrázek na vrstvy s vaším API klíčem Seevio. Úlohy běží asynchronně; uložte si taskId a dotazujte se na stav úlohy, nebo přijměte callback.

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

Obrázek na obrázek

Pro úpravu obrázků nastavte generation_type na image-to-image a zadejte image_urls. Všechny ostatní parametry používají stejný kontrakt.

Nahraďte ukázkové adresy URL z example.com vlastními veřejně přístupnými soubory na HTTPS. Ukázkové adresy URL slouží pouze pro ilustraci struktury požadavku a nelze je stáhnout.

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

Rozklad na vrstvy

Nastavte parametr generation_type na layer-decomposition a zadejte přesně jednu URL adresu obrázku. Vynechejte aspect_ratio. Parametr output_format ovlivňuje pouze formát základního obrázku. Oddělené vrstvy jsou vždy vráceny ve formátu PNG se zachovanou průhledností. Uložte každou URL adresu vrácenou v data.results.

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

Rozklad na vrstvy může v data.results vrátit více URL adres obrázků: základní obrázek a oddělené vrstvy. Každá URL adresa ukazuje na samostatný obrázek. Počet výsledků se liší podle úlohy (celkem 1–17 obrázků); zpracovávejte celé pole, nikoli pouze data.results[0]. Toto pole obsahuje jak odpověď na dokončenou úlohu, tak webhook o dokončení. Původní odpověď při vytvoření obsahuje taskId a rezervované kredity, nikoli URL adresy obrázků.

Příklad odpovědi při vytvoření úlohy

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

Dokončený rozklad na vrstvy: více URL adres obrázků

Tato ukázková odpověď zobrazuje čtyři výstupní obrázky: jeden základní obrázek a tři vrstvy. Vaše úloha může vrátit jiný počet. Při vyžádaném rozlišení 2K představuje hodnota credits konečnou cenu za všechny čtyři obrázky; nepoužitá část původní rezervace na 17 obrázků byla vrácena zpět.

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

Zpracujte každý vrácený obrázek

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.

Dotaz na stav úlohy

Nahraďte ukázkové ID za taskId vrácené při vytvoření. Dotazy vracejí pouze úlohy patřící uživateli daného API klíče; nepřístupná nebo neznámá ID vrací HTTP 404.

Jako výchozí bod se dotazujte každých 10–20 sekund, při chybě HTTP 429 frekvenci snižte a dotazování ukončete, jakmile je stav completed nebo failed. V produkčním prostředí dejte přednost webhookům. Každá ukázka kódu níže provede jeden dotaz.

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

Ve frontě

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

Dokončeno

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

Selhalo

Pokud dotaz vrátí status=failed, generování skončilo neúspěšně. Důvod chyby najdete v failed_reason a výsledek vrácení peněz v billing_status. V tomto příkladu hodnota refunded znamená, že kredity byly vráceny. V credits zůstává původní vyhrazená částka a odpověď neobsahuje žádná data.

{
  "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."
}

Odkazy na výsledky jsou k dispozici po dobu 30 dnů od uložení. Po uplynutí této doby je pole results prázdné.

Webhooky

Nastavením callback_url v požadavku na vytvoření obdržíte JSON POST požadavek při dokončení nebo selhání úlohy. Odpovězte stavovým kódem 2xx do 15 sekund. Neúspěšná doručení se opakují; opakovaná doručení zpracovávejte idempotentně podle ID úlohy.

Koncový bod pro zpětné volání (callback) musí přijímat požadavky typu POST s tělem ve formátu JSON (Content-Type: application/json).

Vytvoření úlohy s callbackem

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

Zpětná volání (callbacks) využívají strukturu odpovědi na dotaz na úlohu (task query); oznámení o neúspěchu s vrácením prostředků obsahují také credits_refunded na nejvyšší úrovni. K identifikaci úlohy použijte id a pro rozlišení úspěšného či neúspěšného dokončení status. Oznámení se mohou opakovat: zpracovávejte je idempotentně podle id a status. Zpětná volání nejsou podepsaná; úlohu si ověřte pomocí autorizovaného koncového bodu pro dotazy. Selhání doručení zpětného volání nevede k vrácení kreditů za úspěšně dokončenou úlohu.

Úloha byla dokončena: callback s úspěšným výsledkem

created_at je čas vytvoření události, task_created_at čas vytvoření úlohy, v sekundách Unix. Příklady ukazují doporučená pole; odpovědi mohou obsahovat další pole.

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

Úloha selhala: callback s chybovým hlášením

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

Příklad přijímače

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 });
}

Tento příklad v Next.js načítá tělo callbacku ve formátu JSON a rovnou zpracovává dokončené i neúspěšné úlohy. Do své aplikace přidejte perzistentní ukládání a deduplikaci podle ID úloh. Náročnější operace zařazujte do fronty ještě před potvrzením přijetí callbacku.

Chyby

Chyby HTTP obsahují objekt error s poli code a message. Úspěšně přijatá úloha může přesto později selhat; dotazujte se na stav úlohy nebo ošetřete callback o jejím selhání.

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

Chyby využívají formát error.code a error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Chyba 402 insufficient_credits znamená, že pro tento požadavek nemáte dostatek kreditů.

Limity četnosti požadavků

Vytváření úkolů: každý API klíč standardně umožňuje až 100 požadavků za minutu. Vlastní limity četnosti v současné době nejsou k dispozici.

Dotazování na úkoly: každý API klíč standardně umožňuje až 120 požadavků za minutu. Požadavky na dotazy a požadavky na vytváření úkolů se počítají samostatně.

Požadavky na tvorbu obrázků a videí sdílejí stejný limit frekvence volání (rate limit) pro daný API klíč.

Chyba HTTP 429 obsahuje hlavičku Retry-After: 60 pro vytváření úloh a Retry-After: 5 pro dotazy. Používejte odklad (backoff) a nedotazujte se častěji, než je nutné.

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

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