Seedream v4.5 Edit API: modifica delle immagini in modo programmatico

Eseguire Seedream v4.5 Edit tramite l'interfaccia di Arteza è ideale per modifiche singole e piccoli batch. Per flussi di lavoro ad alto volume, come cataloghi con migliaia di SKU, generazione di immagini dinamica per utente o pipeline di asset gestite da CMS, è preferibile utilizzare l'accesso API. Questa guida illustra la struttura degli endpoint, i parametri delle richieste, la gestione delle risposte e i pattern di produzione per creare sistemi automatizzati di editing delle immagini con Seedream v4.5.

Perché usare l'API

L'API sblocca pattern di automazione che l'interfaccia non può eguagliare:

• Batch ad alto volume. Elabora 1.000 o più modifiche in un'unica esecuzione della pipeline.
• Generazione dinamica. Crea immagini su richiesta da dati utente o record del database.
• Flussi di lavoro pianificati. Aggiornamenti notturni del catalogo, rigenerazione attivata da eventi.
• Integrazione con gli stack esistenti. Node.js, Python, Go, Ruby: qualsiasi client HTTP.
• Produzione riproducibile. Script sotto controllo di versione al posto di clic manuali.

Se il tuo caso d'uso prevede più di 20-50 modifiche simili, l'API vale la pena di essere configurata.

Struttura dell'endpoint

Il modello Seedream v4.5 Edit è disponibile all'indirizzo:

fal-ai/bytedance/seedream/v4.5/edit

Si tratta di un endpoint standard del modello fal.ai che può essere chiamato direttamente o tramite il sistema di crediti di Arteza.

Autenticazione

Le richieste all'API di Arteza si autenticano tramite una chiave API passata nell'header Authorization come token Bearer.

Ottenere la propria chiave API

1. Accedi su arteza.ai
2. Vai alle impostazioni del tuo account
3. Trova la sezione API
4. Genera una nuova chiave API
5. Conservala in modo sicuro: trattala come una password

Non inserire mai la chiave API nel controllo del codice sorgente. Usa le variabili d'ambiente:

export SEEDANCE_API_KEY="your_api_key_here"

Header di autenticazione

Authorization: Bearer your_api_key_here

Struttura della richiesta

Una richiesta di base a Seedream v4.5 Edit è strutturata così:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Riferimento ai parametri

Puoi passare fino a 10 URL di immagini. Il modello tratta la prima immagine come primaria e le successive come riferimento.

Esempio di richiesta: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Esempio di richiesta: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Struttura della risposta

Una risposta riuscita include gli URL delle immagini generate:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Scarica l'immagine dall'URL restituito: gli URL di output sono validi per 24 ore.

Pattern di generazione asincrona

Seedream v4.5 Edit impiega 30-60 secondi per richiesta. In produzione è preferibile usare la generazione asincrona con webhook o polling invece di richieste bloccanti.

Asincrono con webhook

Passa un webhook_url nella tua richiesta e Arteza invierà il risultato tramite POST quando la generazione è completata:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Il tuo handler del webhook riceve:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

La gestione tramite webhook è il pattern di produzione consigliato.

Inizia a costruire. Prova prima lo strumento.

Asincrono con polling

Se la tua infrastruttura non può ricevere webhook, puoi fare polling per lo stato:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Poll per il completamento
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Esegui il polling ogni 5-10 secondi. L'attesa totale è solitamente di 30-60 secondi.

Pattern di produzione

Pattern 1: generazione batch del catalogo

Esegui l'API sull'intero catalogo prodotti per generare sostituzioni dello sfondo coerenti per ogni SKU:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Abbina un handler webhook che salva gli output sul tuo CDN e aggiorna il record del prodotto.

Pattern 2: modifiche utente su richiesta

Permetti agli utenti di caricare immagini e ottenere risultati modificati dall'AI su richiesta:

1. L'utente carica l'immagine nel tuo bucket
2. Il tuo backend chiama Seedream v4.5 Edit con un prompt scelto dall'utente
3. Esegui il polling o attendi il webhook
4. Restituisci l'URL del risultato al client dell'utente

Prevedi circa 60 secondi di attesa per modifica nella tua UX.

Pattern 3: pipeline di asset guidata dal CMS

Quando il contenuto viene pubblicato nel tuo CMS, genera automaticamente le immagini associate:

1. Il CMS emette un evento di pubblicazione
2. Una funzione serverless si attiva
3. Chiama Seedream v4.5 Edit con un prompt template
4. Salva il risultato sul CDN
5. Aggiorna il record del CMS con l'URL dell'immagine

Questo pattern elimina la creazione manuale delle immagini per la pubblicazione ad alto volume.

Gestione degli errori

Risposte di errore più comuni:

Racchiudi sempre le chiamate API in try/except con logica di retry per le risposte 429 e 500.

Limiti di frequenza

Arteza applica limiti di frequenza ragionevoli sull'API. Per la maggior parte dei flussi di produzione non li raggiungerai, ma per batch in blocco di 1.000 o più richieste, implementa:

• Backoff esponenziale sulle risposte 429
• Limiti alle richieste concorrenti (inizia con 5 in parallelo, poi regola)
• Accodamento delle richieste per un throughput prevedibile

Contatta il supporto per limiti di frequenza più elevati su carichi di lavoro di produzione intensi.

Costo a volume API

Le chiamate API hanno lo stesso costo delle chiamate dall'interfaccia: 1 crediti ($0,10) per immagine. A scopo di pianificazione:

• 100 chiamate API = 100 crediti (ampiamente nel piano Starter da $5)
• 1.000 chiamate API = 1.000 crediti (piano Studio da $120, 1.800 al mese)
• 10.000 chiamate API = 10.000 crediti (piano Studio da $120 più circa 8.200 crediti in ricariche)

Per volumi superiori a 10.000 al mese, contatta il team per un'offerta personalizzata.

Best practice

1. Usa i webhook in produzione. Il polling funziona ma spreca risorse.
2. Salva i prompt nel controllo di versione. Tratta i prompt come codice.
3. Registra tutto. ID delle richieste, prompt, output, errori.
4. Valida gli input prima di chiamare. URL di immagini errati sprecano crediti.
5. Monitora il saldo dei crediti. Imposta un avviso quando scendi sotto una soglia.
6. Testa le modifiche ai prompt in staging. Valida su 3-5 immagini prima di eseguire un batch completo.
7. Metti in cache i risultati. Se gli input sono identici, riutilizza gli output precedenti.

Approfondimenti

• Guida completa alla modifica con Seedream v4.5
• Tutorial per la modifica in batch
• Dettaglio dei prezzi

Per iniziare

Genera la tua chiave API nella dashboard di Arteza, ottieni 10 crediti gratuiti ed esegui l'esempio Node.js riportato sopra con una foto prodotto. L'API sblocca tutto il potenziale produttivo di Seedream v4.5 Edit: una volta configurata, il resto è tutto prompt engineering. Per testare prima in modo pratico, apri lo strumento web e valida i tuoi prompt prima di automatizzare.