Seedream 5.0 Pro API

Funzionalità

Prezzi e crediti

I prezzi indicati di seguito si intendono per singola immagine restituita. La generazione ordinaria riserva un'immagine. La scomposizione in livelli riserva 17 immagini, addebita il conteggio effettivo restituito (inclusa l'immagine di base) e riaccredita i crediti non utilizzati sul saldo originale. Le attività non riuscite vengono rimborsate interamente.

Alla risoluzione predefinita di 2K, la scomposizione in livelli riserva 136 crediti. Se vengono restituite quattro immagini, l'addebito finale è di 32 crediti e vengono restituiti 104 crediti.

L'idempotenza delle richieste non è supportata. Ogni richiesta POST valida crea un nuovo task fatturabile. Se l'esito di un invio non è sicuro, interroga il taskId restituito; ripetere la POST potrebbe creare un altro task.

Autenticazione

Crea una chiave API nella dashboard. La chiave completa viene mostrata una sola volta. Conservala sul tuo server e inviala come token Bearer in ogni richiesta.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Imposta la variabile d'ambiente SEEVIO_API_KEY prima di eseguire questi esempi. Gli esempi in JavaScript vengono eseguiti sul server con Node.js; gli esempi in Python utilizzano la libreria requests.

Corpo della richiesta

Parametri di input

Ogni richiesta crea un singolo task. Le modalità text-to-image e image-to-image restituiscono un'immagine; la scomposizione in livelli (layer-decomposition) restituisce da 1 a 17 immagini, inclusa quella di base. Non inviare il parametro aspect_ratio per la scomposizione in livelli.

Avvio rapido

Invia questa richiesta minima, salva il taskId restituito e usa l'esempio di query del task riportato di seguito. Il valore dei crediti nella risposta di creazione corrisponde all'importo prenotato.

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

Esempio di risposta alla creazione del task

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

Da testo a immagine

Genera immagini, modifica riferimenti o scomponi un'immagine in livelli con la tua chiave API Seevio. Le attività vengono eseguite in modo asincrono; salva il taskId ed esegui il polling dell'endpoint dell'attività o ricevi una 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"
  }
}'

Da immagine a immagine

Per l'editing di immagini, imposta generation_type su image-to-image e fornisci gli image_urls. Tutti gli altri parametri utilizzano le stesse specifiche.

Sostituisci gli URL di esempio con i tuoi file HTTPS accessibili pubblicamente. Gli URL di esempio servono solo a illustrare la struttura della richiesta e non sono risorse scaricabili.

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

Scomposizione in livelli

Imposta generation_type su layer-decomposition e fornisci esattamente un URL dell'immagine. Ometti aspect_ratio. output_format controlla solo il formato dell'immagine di base. I livelli separati vengono sempre restituiti in formato PNG con trasparenza preservata. Salva ogni URL presente in 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"
  }
}'

La scomposizione in livelli può restituire più URL di immagini in data.results: l'immagine di base e i livelli separati. Ogni URL punta a un'immagine distinta. Il numero di risultati varia in base all'attività (da 1 a 17 immagini in totale); elabora l'intero array anziché solo data.results[0]. Sia la query dell'attività completata che il webhook di completamento contengono questo array. La risposta di creazione iniziale contiene taskId e i crediti riservati, non gli URL delle immagini.

Esempio di risposta alla creazione del task

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

Scomposizione in livelli completata: URL di immagini multiple

Questa risposta illustrativa mostra quattro immagini di output: un'immagine di base e tre livelli. La tua attività potrebbe restituire un numero diverso di immagini. Alla risoluzione 2K richiesta, credits rappresenta l'addebito finale per tutte e quattro le immagini; la parte non utilizzata della prenotazione iniziale di 17 immagini è stata restituita.

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

Elabora ogni immagine restituita

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.

Interroga un task

Sostituisci l'ID di esempio con il taskId restituito alla creazione. Le query restituiscono solo i task associati all'utente della chiave API; ID non accessibili o inesistenti restituiscono HTTP 404.

Come punto di partenza, effettua un polling ogni 10–20 secondi, rallenta le richieste in caso di HTTP 429 e interrompi quando lo stato diventa completed o failed. Per gli ambienti di produzione, consigliamo l'uso dei webhook. Ogni esempio di codice seguente esegue una singola query.

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

In coda

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

Completato

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

Fallito

Se la query restituisce status=failed, significa che la generazione non è andata a buon fine. Consulta failed_reason per conoscerne il motivo e billing_status per l'esito del rimborso. In questo esempio, lo stato refunded indica che i crediti sono stati riaccreditati. La voce credits mostra la quota inizialmente prenotata e la risposta non include la chiave 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."
}

I link dei risultati sono disponibili per 30 giorni dall'archiviazione. Dopo la scadenza, il campo results sarà vuoto.

Webhook

Imposta callback_url nella richiesta di creazione per ricevere una richiesta POST JSON al completamento o al fallimento del task. Restituisci una risposta 2xx entro 15 secondi. Gli invii non riusciti verranno riprovati; gestisci le notifiche duplicate in modo idempotente tramite l'ID del task.

L'endpoint di callback deve accettare richieste POST con un corpo in formato JSON (Content-Type: application/json).

Crea un task con 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"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

I callback utilizzano la struttura di risposta della query del task; le notifiche di errore con rimborso includono anche credits_refunded a livello principale. Usa id per identificare il task e status per distinguere tra completati e falliti. Le notifiche potrebbero essere ripetute: gestiscile in modo idempotente per id e status. I callback non sono firmati; verifica il task con l'endpoint di query autenticato. La mancata consegna non prevede il rimborso di un task completato con successo.

Attività completata: payload di callback riuscito

created_at indica la creazione dell’evento; task_created_at quella del task, in secondi Unix. Gli esempi mostrano i campi consigliati; le risposte possono contenere campi aggiuntivi.

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

Attività non riuscita: payload di callback fallito

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

Esempio di ricevitore

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

Questo esempio in Next.js legge il corpo JSON della callback e gestisce direttamente le attività completate e fallite. Ti consigliamo di aggiungere logiche di persistenza e deduplicazione dei task-ID per la tua applicazione, e di accodare i processi più lenti prima di confermare la callback.

Errori

Gli errori HTTP contengono un oggetto error con code e message. Un task accettato correttamente può comunque fallire in una fase successiva; interroga lo stato del task o gestisci la chiamata di callback per l'errore.

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

Gli errori utilizzano error.code ed error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Un errore 402 insufficient_credits indica che i crediti disponibili non sono sufficienti per questa richiesta.

Limiti di frequenza

Creazione task: per impostazione predefinita, ciascuna chiave API consente fino a 100 richieste al minuto. Al momento non sono disponibili limiti di frequenza personalizzati.

Interrogazione task: per impostazione predefinita, ciascuna chiave API consente fino a 120 richieste al minuto. Le richieste di interrogazione e quelle di creazione dei task vengono conteggiate separatamente.

Le richieste di creazione di immagini e video condividono lo stesso limite di frequenza (rate limit) della chiave API.

La risposta HTTP 429 include Retry-After: 60 per la creazione e Retry-After: 5 per le query. Applica un backoff ed evita di interrogare lo stato con una frequenza eccessiva.

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

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