Seedream 5.0 Flash API

Ominaisuudet

Hinnoittelu ja krediitit

Alla olevat hinnat ovat palautettua kuvaa kohden. Tavallinen luonti varaa yhden kuvan hinnan. Tasoihin jako varaa 17 kuvan hinnan, veloittaa todellisen palautetun määrän (mukaan lukien pohjakuva) ja palauttaa käyttämättömät krediitit alkuperäiseen saldoon. Epäonnistuneet tehtävät hyvitetään kokonaisuudessaan.

Oletusarvoisella 2K-tarkkuudella tasoihin jako varaa 34 krediittiä. Jos pyyntö palauttaa neljä kuvaa, lopullinen veloitus on 8 krediittiä ja 26 krediittiä palautetaan tilille.

Pyyntöjen idempotenssia ei tueta. Jokainen kelvollinen POST-pyyntö luo uuden maksullisen tehtävän. Jos lähetyksen tulos on epävarma, tee kysely palautetulla taskId-tunnuksella. POST-pyynnön yrittäminen uudelleen voi luoda toisen tehtävän.

Autentikointi

Luo API-avain hallintapaneelissa. Täydellinen avain näytetään vain kerran. Säilytä se turvallisesti palvelimellasi ja lähetä se Bearer-tokenina jokaisen pyynnön yhteydessä.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Aseta SEEVIO_API_KEY-ympäristömuuttuja ennen näiden esimerkkien suorittamista. JavaScript-esimerkit ajetaan palvelimellasi Node.js-ympäristössä; Python-esimerkeissä käytetään requests-kirjastoa.

Pyyntörunko

Syöteparametrit

Jokainen pyyntö luo yhden tehtävän. Tekstistä kuvaksi (text-to-image) ja kuvasta kuvaksi (image-to-image) palauttavat yhden kuvan; tasoihin jako (layer-decomposition) palauttaa 1–17 kuvaa, mukaan lukien pohjakuvan. Älä lähetä kuvasuhdetta (aspect_ratio) käytettäessä tasoihin jakoa.

Pika-aloitus

Lähetä tämä minimipyyntö, tallenna palautettu taskId ja käytä alla olevaa tehtäväkyselyn esimerkkiä. Luontivastauksessa näkyvä krediittisumma on varattu enimmäismäärä.

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

Esimerkki tehtävän luonnin vastauksesta

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

Tekstistä kuvaksi

Luo kuvia, muokkaa viitekuvia tai jaa kuva tasoihin Seevio API-avaimellasi. Tehtävät ajetaan asynkronisesti; tallenna taskId ja tee kyselyitä tehtävän päätepisteeseen tai vastaanota callback-kutsu.

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

Kuvasta kuvaksi

Jos haluat muokata kuvaa, aseta parametrin generation_type arvoksi image-to-image ja määritä kuvan osoitteet kohtaan image_urls. Kaikki muut parametrit noudattavat samoja määrityksiä.

Korvaa example.com-esimerkkiosoitteet omilla julkisilla HTTPS-tiedostoillasi. Esimerkki-URL-osoitteet on tarkoitettu havainnollistamaan pyynnön rakennetta, eivätkä ne ole ladattavia esimerkkiversioita.

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

Tasoihin jako

Aseta parametrin generation_type arvoksi layer-decomposition ja anna tasan yksi kuvan URL-osoite. Jätä aspect_ratio pois. Parametri output_format määrittää vain pohjakuvan muodon. Erotetut tasot palautetaan aina PNG-muodossa läpinäkyvyys säilytettynä. Tallenna jokainen data.results-kentässä palautettu URL-osoite.

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

Tasoihin jako voi palauttaa useita kuva-URL-osoitteita kentässä data.results: pohjakuvan sekä erotellut tasot. Jokainen URL osoittaa erilliseen kuvaan. Tulosten määrä vaihtelee tehtäväkohtaisesti (yhteensä 1–17 kuvaa); käsittele koko taulukko sen sijaan, että lukisit vain data.results[0] -arvon. Sekä valmiin tehtävän kyselyvastaus että onnistumisesta ilmoittava webhook-kutsu sisältävät tämän taulukon. Alkuperäinen luontivastaus sisältää taskId-tunnuksen ja varatut krediitit, ei kuva-URL-osoitteita.

Esimerkki tehtävän luonnin vastauksesta

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

Valmis tasoihin jako: useita kuva-URL-osoitteita

Tämä esimerkkivastaus näyttää neljä tuloskuvaa: yhden pohjakuvan ja kolme tasoa. Tehtäväsi voi palauttaa eri määrän kuvia. Pyydetyllä 2K-tarkkuudella credits on kaikkien neljän kuvan lopullinen veloitus; alkuperäisen 17 kuvan varauksen käyttämätön osa on palautettu.

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

Käsittele jokainen palautettu kuva

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.

Tehtävän kysely

Korvaa esimerkkitunnus luonnin yhteydessä palautetulla taskId-tunnuksella. Kyselyt palauttavat vain ne tehtävät, jotka kuuluvat kyseisen API-avaimen käyttäjälle; tuntemattomat tunnukset palauttavat virheen HTTP 404.

Tee kyselyitä aluksi 10–20 sekunnin välein, hidasta tahtia, jos saat virheen HTTP 429, ja lopeta kyselyt, kun tilaksi vaihtuu completed tai failed. Suosi webhookeja tuotantoympäristössä. Jokainen alla oleva koodiesimerkki tekee yhden kyselyn.

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

Jonossa

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

Valmis

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

Epäonnistunut

Kun kysely palauttaa arvon status=failed, luonti on epäonnistunut. Kohdasta failed_reason näet virheen syyn ja kohdasta billing_status hyvityksen tilanteen. Tässä esimerkissä tila refunded tarkoittaa, että krediitit on palautettu. credits-kentässä näkyy alkuperäinen varattu määrä, eikä vastaus sisällä data-kenttää.

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

Tuloslinkit ovat käytettävissä 30 päivän ajan tallennuksesta. Sen jälkeen results-kenttä on tyhjä.

Webhookit

Aseta callback_url-osoite luontipyyntöön vastaanottaaksesi JSON-muotoisen POST-kutsun, kun tehtävä valmistuu tai epäonnistuu. Palauta 2xx-vastaus 15 sekunnin kuluessa. Epäonnistuneita lähetyksiä yritetään uudelleen; käsittele toistuvat kutsut idempotentisti tehtävätunnuksen (task ID) perusteella.

Takaisinkutsun päätepisteen on hyväksyttävä POST-pyyntöjä, joiden runko on JSON-muotoinen (Content-Type: application/json).

Luo tehtävä webhook-paluukutsulla

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

Takaisinkutsut käyttävät tehtäväkyselyn vastausrakennetta. Hyvitetyistä epäonnistumisista kertovissa ilmoituksissa on mukana myös ylätason tieto credits_refunded. Tunnista tehtävä id-kentän avulla ja erota onnistuneet ja epäonnistuneet tehtävät status-kentän perusteella. Ilmoitukset saattavat toistua, joten käsittele ne idempotentisti id- ja status-kenttien mukaan. Takaisinkutsuja ei allekirjoiteta. Varmista tehtävän tila tunnistautumista vaativasta kyselyrajapinnasta. Toimituksen epäonnistuminen ei johda onnistuneen tehtävän hyvittämiseen.

Tehtävä valmis: onnistuneen kutsun hyötykuorma

created_at on tapahtuman luontiaika ja task_created_at tehtävän luontiaika Unix-sekunteina. Esimerkit näyttävät suositellut kentät; vastaukset voivat sisältää lisäkenttiä.

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

Tehtävä epäonnistui: epäonnistuneen kutsun hyötykuorma

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

Esimerkki vastaanottimesta

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

Tässä Next.js-esimerkissä luetaan JSON-muotoinen takaisinkutsun runko ja käsitellään onnistuneet sekä epäonnistuneet tehtävät suoraan. Lisää sovellukseesi tiedon säilytys ja tehtävätunnusten (task-ID) duplikaattien poisto. Aseta hitaat työt jonoon ennen takaisinkutsun kuittaamista.

Virheet

HTTP-virheiden yhteydessä palautetaan error-objekti, jossa on kentät code ja message. Onnistuneesti vastaanotettu tehtävä voi silti epäonnistua myöhemmin; tee tehtäväkysely tai käsittele epäonnistumisesta tuleva webhook-kutsu.

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

Virheissä käytetään muotoa error.code ja error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Virhe 402 insufficient_credits tarkoittaa, että käytettävissä olevat krediittisi eivät riitä tähän pyyntöön.

Käyttörajat

Tehtävien luonti: kukin API-avain sallii oletusarvoisesti enintään 100 pyyntöä minuutissa. Mukautettuja pyyntörajoituksia ei ole tällä hetkellä saatavilla.

Tehtävien kyselyt: kukin API-avain sallii oletusarvoisesti enintään 120 pyyntöä minuutissa. Kyselypyynnöt ja tehtävien luontipyynnöt lasketaan erikseen.

Kuva- ja videopyynnöt jakavat saman API-avaimen kutsurajoituksen (rate limit).

Virhe HTTP 429 sisältää otsikon Retry-After: 60 luontipyynnöille ja Retry-After: 5 kyselyille. Käytä viivästettyjä uusintayrityksiä (backoff) ja vältä tarpeettoman tiheitä kyselyitä.

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

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