Seedream 5.0 Flash API

Możliwości

Cennik i kredyty

Poniższe ceny dotyczą pojedynczego zwróconego obrazu. Zwykłe generowanie rezerwuje opłatę za jeden obraz. Rozkład na warstwy rezerwuje opłatę za 17 obrazów, następnie rozlicza rzeczywistą liczbę zwróconych obrazów (w tym obraz bazowy) i zwraca niewykorzystane kredyty na pierwotne saldo. Za nieudane zadania zwracana jest pełna kwota.

Przy domyślnej rozdzielczości 2K liczba kredytów rezerwowanych na rozkład na warstwy wynosi 34. Jeśli zwrócone zostaną cztery obrazy, opłata końcowa (w kredytach) wyniesie 8, a zwrot — 26.

Idempotentność żądań nie jest obsługiwana. Każde prawidłowe żądanie POST tworzy nowe, płatne zadanie. Jeśli status wysłanego żądania jest niepewny, należy sprawdzić zwrócony taskId – ponowne wysłanie żądania POST może utworzyć kolejne zadanie.

Uwierzytelnianie

Utwórz klucz API w panelu użytkownika. Pełny klucz zostanie wyświetlony tylko raz. Przechowuj go bezpiecznie na swoim serwerze i przesyłaj w nagłówku jako token Bearer przy każdym żądaniu.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Przed uruchomieniem poniższych przykładów ustaw zmienną środowiskową SEEVIO_API_KEY. Przykłady w JavaScript należy uruchamiać na serwerze przy użyciu Node.js; przykłady w Pythonie korzystają z pakietu requests.

Treść żądania

Parametry wejściowe

Każde żądanie tworzy jedno zadanie. Funkcje text-to-image oraz image-to-image zwracają jeden obraz; funkcja layer-decomposition zwraca od 1 do 17 obrazów, w tym obraz bazowy. Nie należy przesyłać parametru aspect_ratio dla funkcji layer-decomposition.

Szybki start

Wyślij to proste żądanie, zapisz zwrócony identyfikator taskId, a następnie użyj poniższego przykładu odpytywania o stan zadania. Liczba kredytów w odpowiedzi na utworzenie zadania to kwota zarezerwowana.

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

Przykładowa odpowiedź na utworzenie zadania

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

Tekst na obraz

Generuj obrazy, edytuj materiały referencyjne lub rozkładaj obrazy na warstwy za pomocą klucza API Seevio. Zadania są uruchamiane asynchronicznie; zapisz taskId i odpytuj punkt końcowy zadania lub odbierz wywołanie zwrotne.

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

Obraz na obraz

W przypadku edycji obrazu należy ustawić parametr generation_type na image-to-image i podać adresy w image_urls. Wszystkie pozostałe parametry korzystają z tego samego kontraktu danych.

Zastąp przykładowe adresy URL multimediów z domeny example.com własnymi, publicznie dostępnymi plikami HTTPS. Przykładowe adresy pokazują strukturę żądania i nie są plikami do pobrania.

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

Rozkład na warstwy

Ustaw parametr generation_type na layer-decomposition i podaj dokładnie jeden adres URL obrazu. Pomiń parametr aspect_ratio. Parametr output_format kontroluje wyłącznie format obrazu bazowego. Wyodrębnione warstwy są zawsze zwracane w formacie PNG z zachowaniem przezroczystości. Zapisz każdy adres URL zwrócony w 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-flash",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

Rozkład na warstwy może zwrócić wiele adresów URL obrazów w data.results: obraz bazowy oraz oddzielone warstwy. Każdy adres URL wskazuje na osobny plik. Liczba wyników zależy od zadania (łącznie od 1 do 17 obrazów); przetwórz całą tablicę, a nie tylko element data.results[0]. Zarówno odpowiedź z zapytania o ukończone zadanie, jak i webhook zawierają tę tablicę. Pierwsza odpowiedź na utworzenie zadania zawiera taskId i zarezerwowane kredyty, a nie adresy URL obrazów.

Przykładowa odpowiedź na utworzenie zadania

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

Ukończony rozkład na warstwy: wiele adresów URL obrazów

Ta przykładowa odpowiedź pokazuje cztery obrazy wyjściowe: jeden obraz bazowy i trzy warstwy. Twoje zadanie może zwrócić inną liczbę plików. Przy żądanej rozdzielczości 2K pole credits przedstawia ostateczną opłatę za wszystkie cztery obrazy; niewykorzystana część początkowej rezerwacji na 17 obrazów została zwrócona.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-flash",
  "credits": 8,
  "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
  }
}

Przetwarzaj każdy zwrócony obraz

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.

Sprawdź stan zadania

Zastąp przykładowy identyfikator wartością taskId otrzymaną przy tworzeniu zadania. Zapytania zwracają wyłącznie zadania należące do użytkownika powiązanego z danym kluczem API; nieznane lub niedostępne identyfikatory zwracają HTTP 404.

Na początek odpytuj o stan co 10–20 sekund, wydłużaj odstępy w przypadku błędu HTTP 429 i przerwij, gdy status zmieni się na completed lub failed. W środowisku produkcyjnym zalecamy korzystanie z webhooków. Każdy poniższy przykład kodu wykonuje jedno zapytanie.

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

W kolejce

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

Zakończone sukcesem

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-flash",
  "credits": 2,
  "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
  }
}

Błąd

Gdy zapytanie zwróci status=failed, oznacza to, że generowanie zakończyło się niepowodzeniem. Przyczynę błędu znajdziesz w polu failed_reason, a wynik zwrotu środków w billing_status. W tym przykładzie status refunded oznacza, że kredyty zostały zwrócone. Pole credits zachowuje pierwotnie zarezerwowaną wartość, a odpowiedź nie zawiera obiektu data.

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

Linki do wyników są dostępne przez 30 dni od momentu zapisu. Po upływie tego okresu pole results pozostaje puste.

Webhooki

Ustaw parametr callback_url w żądaniu utworzenia, aby otrzymać żądanie POST z formatem JSON, gdy zadanie zostanie zakończone sukcesem lub błędem. Zwróć odpowiedź z kodem 2xx w ciągu 15 sekund. Nieudane doręczenia są ponawiane; powtarzające się wywołania należy przetwarzać idempotentnie na podstawie identyfikatora zadania.

Twój punkt końcowy (callback endpoint) musi akceptować żądania POST z treścią w formacie JSON (Content-Type: application/json).

Utwórz zadanie z wywołaniem zwrotnym (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-flash",
  "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"
}'

Wywołania zwrotne (callbacks) korzystają ze struktury odpowiedzi zapytania o zadanie (task query); powiadomienia o niepowodzeniu ze zwrotem środków zawierają dodatkowo parametr credits_refunded na poziomie głównym. Użyj parametru id do identyfikacji zadania oraz status, aby odróżnić zadania ukończone od nieudanych. Powiadomienia mogą się powtarzać: przetwarzaj je idempotentnie na podstawie id oraz status. Wywołania zwrotne nie są podpisane cyfrowo; zweryfikuj stan zadania za pomocą uwierzytelnionego punktu końcowego zapytania. Brak dostarczenia powiadomienia nie skutkuje zwrotem środków za pomyślnie wykonane zadanie.

Zadanie zakończone: struktura danych pomyślnego wywołania zwrotnego

created_at oznacza czas utworzenia zdarzenia, a task_created_at zadania, w sekundach Unix. Przykłady pokazują zalecane pola; odpowiedzi mogą zawierać dodatkowe pola.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-flash",
  "credits": 2,
  "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
}

Zadanie nie powiodło się: struktura danych błędu wywołania zwrotnego

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-flash",
  "credits": 2,
  "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": 2
}

Przykładowy odbiorca

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

Ten przykład dla Next.js odczytuje treść wywołania zwrotnego JSON i bezpośrednio obsługuje zakończone oraz nieudane zadania. W swojej aplikacji dodaj mechanizm trwałości danych oraz deduplikację identyfikatorów zadań (task-ID). Przed potwierdzeniem odbioru wywołania zwrotnego dodaj czasochłonne operacje do kolejki.

Błędy

Błędy HTTP zawierają obiekt error z polami code i message. Pomyślnie przyjęte zadanie może nadal zakończyć się błędem na późniejszym etapie – sprawdzaj stan zadania lub obsłuż wywołanie zwrotne (callback) informujące o błędzie.

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

Błędy używają formatu error.code i error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Błąd 402 insufficient_credits oznacza, że Twoje dostępne kredyty są niewystarczające do realizacji tego żądania.

Limity żądań

Tworzenie zadań: każdy klucz API pozwala domyślnie na maksymalnie 100 żądań na minutę. Niestandardowe limity żądań nie są obecnie dostępne.

Zapytania o zadania: każdy klucz API pozwala domyślnie na maksymalnie 120 żądań na minutę. Zapytania i żądania utworzenia zadań są liczone oddzielnie.

Żądania generowania obrazów i wideo współdzielą ten sam limit zapytań (rate limit) przypisany do klucza API.

Błąd HTTP 429 zawiera nagłówek Retry-After: 60 dla tworzenia zadań oraz Retry-After: 5 dla zapytań o stan. Stosuj algorytm ponawiania z opóźnieniem (backoff) i unikaj zbyt częstego odpytywania.

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

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