L’API GPT Image 2.5 è disponibile. Crea e modifica immagini →
PoYoPoYo
tutorials

Guida all'API Seedream 5.0 Pro: generazione e modifica di immagini con codice

Poyo.ai Team
6 min read
Share:

Guida all'API Seedream 5.0 Pro

Seedream 5.0 Pro API offre agli sviluppatori l'accesso al modello di generazione e modifica delle immagini di punta di ByteDance attraverso un flusso di lavoro asincrono orientato alla produzione. Questa guida mostra come inviare lavori di conversione del testo in immagine e di modifica delle immagini tramite Poyo.ai, quindi recuperare il risultato con il polling o un webhook.

Il prezzo attuale è di 15 crediti, circa $0.075 per immagine generata, per entrambe le varianti di modello.

Modelli e parametri API

Flusso di lavoroID modello
Testo in immagineseedream-5.0-pro
Modifica delle immaginiseedream-5.0-pro-edit

Gli input supportati includono:

  • prompt: istruzioni di generazione o modifica richieste
  • size: una risoluzione preimpostata come 1K o 2K o un formato come 1:1, 4:3, 3:4, 16:9 o 9:16
  • n: numero di immagini da generare
  • output_format: jpeg o png
  • image_urls: immagini di riferimento per il modello modificato, fino a 10
  • callback_url: endpoint HTTPS opzionale per notifiche di completamento

Consulta il riferimento API live per lo schema corrente.

1. Crea una chiave API

Crea un account Poyo.ai, apri Gestione delle chiavi API e memorizza la chiave in una variabile di ambiente. Non esporre mai una chiave di produzione nel codice del browser né inserirla in un commit Git.

export POYO_API_KEY="your-api-key"

2. Invia una richiesta di conversione del testo in immagine

Tutti i lavori utilizzano l'endpoint di invio unificato:

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

La risposta contiene un ID attività:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Chiama Seedream 5.0 Pro con JavaScript

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

Utilizza 2K quando la risoluzione conta più di un rapporto fisso. Utilizza un valore delle proporzioni quando il formato di posizionamento è il vincolo principale.

4. Chiama Seedream 5.0 Pro con Python

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. Modifica immagini con più riferimenti

Cambia l'ID del modello e fornisci image_urls. Spiega al modello il contributo di ogni riferimento.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

Per modifiche affidabili, separa la richiesta in tre idee: ruoli di riferimento, modifiche richieste e vincoli di conservazione.

6. Recupera il risultato

L'invio è asincrono. Dopo aver ricevuto task_id, è possibile:

  • eseguire il polling dell'endpoint unificato dello stato delle attività di Poyo.ai; o
  • fornire callback_url ed elaborare il webhook di completamento.

Segui la documentazione sulla gestione delle attività per l'instradamento dello stato corrente e l'oggetto di risposta. Nella produzione, utilizza il backoff esponenziale anziché il polling continuo.

Gestione degli errori

Gestisci questi casi in modo esplicito:

  • 400: parametri del modello non validi, dimensioni non supportate, URL di immagini inaccessibili o JSON non valido
  • 401: chiave API mancante o non valida
  • attività asincrona non riuscita: generazione non riuscita dopo un invio valido
  • Nuovo tentativo del webhook: lo stesso evento di completamento può essere consegnato più di una volta

Archivia l'ID attività con l'ID processo interno, rendi idempotente la gestione del webhook e registra i messaggi di errore del provider senza registrare i segreti.

Lista di controllo della produzione

  • Mantieni le chiavi API lato server.
  • Convalida la lunghezza del prompt e i tipi di immagine URL prima dell'invio.
  • Utilizza le immagini di riferimento HTTPS a cui può accedere il servizio di generazione.
  • Imposta i timeout delle richieste per le chiamate di invio.
  • Riprova in caso di errori di rete temporanei, ma non ritentare ciecamente richieste non valide.
  • Tieni traccia dei costi come number of requested outputs × 15 credits al prezzo attuale.
  • Esamina il testo generato, i dettagli del prodotto e le affermazioni concrete prima della pubblicazione.
  • Aggiungi la moderazione dei contenuti adeguata al tuo prodotto e al tuo mercato.

Quando utilizzare Pro anziché Lite

Utilizza Seedream 5.0 Pro per progetti strutturati, layout densi, testo multilingue e modifiche controllate. Utilizza Seedream 5.0 Lite per lavori di immagini a basso costo e con volumi più elevati in cui non è necessaria una precisione di progettazione di livello professionale.

Per una panoramica non tecnica, leggi Caratteristiche e prezzi Seedream 5.0 Pro. Puoi anche testare visivamente il carico utile API nella pagina del modello Seedream 5.0 Pro.

Domande frequenti

Qual è l'endpoint dell'API Seedream 5.0 Pro?

Invia lavori di generazione e modifica a POST https://api.poyo.ai/api/generate/submit.

Qual è l'ID del modello modificato?

Utilizza seedream-5.0-pro-edit e includi uno o più valori in input.image_urls.

Quante immagini di riferimento sono supportate?

La documentazione Poyo.ai corrente supporta fino a 10 immagini di riferimento per la modifica Seedream 5.0 Pro.

Quanto costa un'immagine API?

Il prezzo attuale Poyo.ai è di 15 crediti, circa $0.075, per ogni immagine generata o modificata.

Share: