Seedream v4.5 Edit API: Modifica immagini a livello di programmazione

Eseguire Seedream v4.5 Edit attraverso l'interfaccia Arteza funziona per modifiche occasionali e piccoli lotti. Per flussi di lavoro ad alto volume - cataloghi con migliaia di SKU, generazione di immagini dinamica per utente, pipeline di asset guidate da CMS - desideri accesso API. Questa guida illustra la struttura dell'endpoint, i parametri della richiesta, la gestione delle risposte e i modelli di produzione per costruire sistemi automatizzati di modifica delle immagini su Seedream v4.5.

Perché usare l'API

L'API sblocca modelli di automazione che l'interfaccia non riesce a eguagliare:

• Raggruppamento ad alto volume. Elabora 1.000+ modifiche in un'unica esecuzione della pipeline.
• Generazione dinamica. Costruisci immagini su richiesta dai dati dell'utente o dai record del database.
• Flussi di lavoro pianificati. Aggiornamenti di cataloghi notturni, rigenerazione attivata da eventi.
• Integrazione con stack esistenti. Node.js, Python, Go, Ruby - qualsiasi client HTTP.
• Produzione riproducibile. Script controllati da versione invece di clic manuali.

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

Struttura dell'Endpoint

Il modello Seedream v4.5 Edit è disponibile su:

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

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

Autenticazione

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

Ottenere la tua chiave API

1. Accedi su arteza.ai
2. Accedi 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 eseguire mai il commit della tua chiave API al controllo del codice sorgente. Usa variabili di ambiente:

export SEEDANCE_API_KEY="your_api_key_here"

Intestazione di autenticazione

Authorization: Bearer your_api_key_here

Struttura della richiesta

Una richiesta di base di Seedream v4.5 Edit assomiglia a questa:

{
  "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 dei parametri

È possibile passare fino a 10 URL di immagini. Il modello tratta la prima immagine come primaria e le immagini successive come riferimenti.

Richiesta di esempio: 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);

Richiesta di esempio: 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 di successo 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.

Modello di generazione asincrona

Seedream v4.5 Edit richiede 30-60 secondi per richiesta. Per la produzione probabilmente desideri la generazione asincrona con webhook o polling invece di richieste bloccanti.

Asincrono basato su Webhook

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

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

Il tuo handler webhook riceve:

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

La gestione dei webhook è il modello di produzione consigliato.

Inizia a costruire. Prova lo strumento prima.

Asincrono basato su Polling

Se la tua infrastruttura non può ricevere webhook, esegui il polling dello 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 for completion
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.

Modelli di produzione

Modello 1: Generazione di lotti di catalogo

Esegui l'API sul tuo catalogo di prodotti per generare scambi di 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 a un handler webhook che salva gli output sul tuo CDN e aggiorna il record del prodotto.

Modello 2: Modifiche utente su richiesta

Consenti agli utenti di caricare immagini e ottenere risultati modificati da AI su richiesta:

1. L'utente carica un'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

Budget per circa 60 secondi di tempo di attesa per modifica nella tua UX.

Modello 3: Pipeline di asset guidate dal CMS

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

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

Questo modello elimina la creazione di immagini manuale per la pubblicazione ad alto volume.

Gestione degli errori

Risposte di errore comuni:

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

Limiti di velocità

Arteza applica limiti di velocità ragionevoli sull'API. Per la maggior parte dei flussi di lavoro di produzione non li raggiungerai, ma per lotti bulk di 1.000+ richieste, implementa:

• Backoff esponenziale su risposte 429
• Limiti di richieste concorrenti (inizia con 5 in parallelo, ottimizza)
• Code di richieste per throughput prevedibile

Contatta il supporto per limiti di velocità più alti su carichi di produzione pesanti.

Costo al volume API

Le chiamate API costano lo stesso delle chiamate all'interfaccia: 8 crediti ($0.08) per immagine. A scopo di pianificazione:

• 100 chiamate API = 800 crediti (tier Starter, $10)
• 1.000 chiamate API = 8.000 crediti (tier Pro, $50)
• 10.000 chiamate API = 80.000 crediti (molteplici tier Studio, circa $650)

Per volumi superiori a 10.000/mese, contatta il team per i prezzi personalizzati.

Best practice

1. Usa webhook in produzione. Il polling funziona ma spreca risorse.
2. Archivia i prompt nel controllo della versione. Tratta i prompt come codice.
3. Registra tutto. ID richiesta, prompt, output, errori.
4. Convalida gli input prima della chiamata. URL di immagini errati sprecano crediti.
5. Monitora il saldo dei crediti. Avvisa quando scendi al di sotto di una soglia.
6. Testa i cambiamenti dei prompt nella staging. Convalida su 3-5 immagini prima di eseguire un lotto completo.
7. Cache dei risultati. Se gli input sono identici, riutilizza gli output precedenti.

Letture ulteriori

• Guida completa alla modifica di Seedream v4.5
• Tutorial di modifica in batch
• Analisi dei prezzi

Inizia

Genera la tua chiave API nella dashboard Arteza, prendi 50 crediti gratuiti, ed esegui l'esempio Node.js sopra con una foto di prodotto. L'API sblocca il pieno potenziale di produzione di Seedream v4.5 Edit - una volta che ce l'hai collegato, tutto il resto è ingegneria dei prompt. Per i test pratici prima, apri lo strumento web e convalida i tuoi prompt prima di automatizzare.