API Seedream v4.5: integra immagini AI nella tua app

Integrare la generazione di immagini AI nella propria app significava scegliere tra tre opzioni pessime: gestire Stable Diffusion in proprio (infrastruttura costosa), pagare le tariffe per token di OpenAI (costi imprevedibili) oppure sottoscrivere un'API in abbonamento (capacità sprecata). L'API Seedream v4.5 è costruita in modo diverso: pagamento per immagine a $0.10, REST standard e tempi di risposta nell'ordine dei secondi. Questa guida ti porta da zero alla prima generazione in meno di 10 minuti.

A cosa serve l'API

L'API Seedream v4.5 è adatta alle applicazioni che necessitano di generazione di immagini AI on demand con costi per immagine prevedibili. Casi d'uso comuni:

Prodotti SaaS che consentono agli utenti di generare immagini come parte del loro flusso di lavoro: strumenti di design, piattaforme di marketing, app per la creazione di contenuti.

Piattaforme e-commerce che generano immagini lifestyle di prodotto o intestazioni di categoria in modo programmatico.

Strumenti di marketing automation che producono visual per campagne a partire da input strutturati.

Sistemi di gestione dei contenuti che offrono la generazione di immagini AI come funzionalità nativa.

Progetti per sviluppatori e script di automazione per qualsiasi flusso di lavoro che richieda generazione di immagini su larga scala.

App mobile che chiamano l'API da un servizio backend per mantenere la generazione delle immagini off-device.

Se il tuo caso d'uso rientra in una di queste categorie, questa guida ti permetterà di integrare rapidamente.

Autenticazione e primi passi

Passaggio 1: ottieni una chiave API

Registrati per creare un account Arteza se non ne hai già uno. Vai alle impostazioni del tuo account e genera una chiave API. Tratta questa chiave come una password: non inserirla mai in repository pubblici.

Passaggio 2: aggiungi crediti al tuo account

L'utilizzo dell'API attinge dallo stesso saldo crediti dell'utilizzo web. I tuoi 10 crediti gratuiti di registrazione funzionano anche per le chiamate API. Per un utilizzo in produzione, sottoscrivi un piano dalla pagina dei prezzi a partire da $5.

Passaggio 3: effettua la prima richiesta

L'endpoint API per Seedream v4.5 è:

POST https://api.arteza.ai/v1/images/generate

Corpo minimo della richiesta:

{
  "model": "seedream-v4-5",
  "prompt": "A cozy bookstore at dusk, warm window light",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

Includi la tua chiave API nell'intestazione Authorization:

Authorization: Bearer YOUR_API_KEY

Riferimento completo dei parametri

Risoluzioni supportate

Seedream v4.5 supporta più opzioni di risoluzione fino a 4 megapixel:

Esempi di codice

Node.js (Fetch)

const generateImage = async (prompt) => {
  const response = await fetch(
    'https://api.arteza.ai/v1/images/generate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SEEDANCE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'seedream-v4-5',
        prompt: prompt,
        width: 2048,
        height: 2048,
        num_images: 1,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Errore API: ${response.status}`);
  }

  const data = await response.json();
  return data.images[0].url;
};

// Utilizzo
const imageUrl = await generateImage(
  'A cozy bookstore at dusk, warm window light, editorial photography'
);
console.log(imageUrl);

Python (Requests)

import os
import requests

def generate_image(prompt, width=2048, height=2048, num_images=1):
    response = requests.post(
        'https://api.arteza.ai/v1/images/generate',
        headers={
            'Authorization': f'Bearer {os.environ["SEEDANCE_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'seedream-v4-5',
            'prompt': prompt,
            'width': width,
            'height': height,
            'num_images': num_images,
        },
    )
    response.raise_for_status()
    data = response.json()
    return [img['url'] for img in data['images']]

# Utilizzo
urls = generate_image(
    'An editorial product photograph of a ceramic coffee mug, '
    'warm morning light, minimalist composition'
)
print(urls)

cURL

curl -X POST https://api.arteza.ai/v1/images/generate \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-5",
    "prompt": "A futuristic city skyline at sunset, cinematic photography",
    "width": 2048,
    "height": 1152,
    "num_images": 1
  }'

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type GenerateRequest struct {
    Model     string `json:"model"`
    Prompt    string `json:"prompt"`
    Width     int    `json:"width"`
    Height    int    `json:"height"`
    NumImages int    `json:"num_images"`
}

func generateImage(prompt string) (string, error) {
    reqBody := GenerateRequest{
        Model:     "seedream-v4-5",
        Prompt:    prompt,
        Width:     2048,
        Height:    2048,
        NumImages: 1,
    }

    jsonData, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest(
        "POST",
        "https://api.arteza.ai/v1/images/generate",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SEEDANCE_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    images := result["images"].([]interface{})
    firstImage := images[0].(map[string]interface{})
    return firstImage["url"].(string), nil
}

Formato della risposta

Le risposte con esito positivo restituiscono JSON con questa struttura:

{
  "id": "gen_abc123xyz",
  "model": "seedream-v4-5",
  "created": 1712764800,
  "images": [
    {
      "url": "https://cdn.arteza.ai/gen/abc123.png",
      "width": 2048,
      "height": 2048,
      "seed": 42871
    }
  ],
  "credits_used": 8,
  "credits_remaining": 1042
}

Gli URL delle immagini sono validi per 24 ore. Scarica e salva le immagini immediatamente se hai bisogno di un accesso permanente.

Vuoi dettagli come questi? Prova Seedream v4.5 gratis →

Pronto per iniziare l'integrazione? Ottieni la tua chiave API →

Gestione degli errori

L'API restituisce i codici di stato HTTP standard:

Esempio di risposta di errore:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Il tuo account non dispone di crediti sufficienti per questa richiesta",
    "credits_required": 8,
    "credits_available": 3
  }
}

Implementa sempre la gestione degli errori e i tentativi ripetuti per gli errori 429 e 500. Non riprovare per gli errori 400 e 401: quelli richiedono di correggere la richiesta stessa.

Buone pratiche per l'uso in produzione

Rate limiting

I limiti di velocità predefiniti consentono una produzione ragionevole. Se hai bisogno di limiti più elevati, contatta il supporto con i dettagli del tuo caso d'uso.

Implementa il backoff esponenziale sugli errori 429:

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return generate_image(prompt)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Numero massimo di tentativi superato")

Gestione dei crediti

Monitora il campo credits_remaining in ogni risposta. Imposta avvisi quando il saldo scende sotto una soglia, in modo da poter ricaricare prima che il traffico di produzione esaurisca tutti i crediti.

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Avviso crediti bassi: {remaining} crediti')

Gestione asincrona

Per le applicazioni rivolte agli utenti, tratta la generazione di immagini come asincrona. Non bloccare il thread UI su una chiamata API da 5-15 secondi. Approcci consigliati:

• Restituisci subito un ID lavoro e fai polling per il completamento
• Usa i webhook (se supportati) per le notifiche di completamento
• Genera in modo speculativo in background e memorizza in cache i risultati

Caching

Le immagini generate sono deterministiche a parità di prompt e seed. Esegui una cache aggressiva tramite hash del prompt per evitare di rigenerare immagini identiche.

import hashlib

def prompt_cache_key(prompt, width, height, seed):
    raw = f'{prompt}|{width}x{height}|{seed}'
    return hashlib.sha256(raw.encode()).hexdigest()

Sicurezza dei prompt

Se la tua app espone i prompt agli utenti finali, implementa un filtraggio dei contenuti prima di inviarli all'API. Arteza ha politiche sui contenuti: i prompt che le violano restituiranno errori, sprecando crediti e causando problemi visibili agli utenti.

Prezzi per l'utilizzo dell'API

L'utilizzo dell'API attinge dal saldo crediti del tuo account allo stesso costo dell'utilizzo web.

I crediti provengono dallo stesso livelli di prezzo indipendentemente dal fatto che tu li utilizzi tramite web o API:

• Starter: $5 = 60 crediti al mese = 60 immagini
• Creator: $25 = 300 crediti al mese = 300 immagini
• Pro: $50 = 700 crediti al mese = 700 immagini
• Studio: $120 = 1.800 crediti al mese = 1.800 immagini

I clienti con volumi elevati possono contattare il supporto per informazioni sui prezzi a volume per un utilizzo continuato superiore a 100.000 immagini al mese.

Combinare con altri modelli Arteza

La tua applicazione può utilizzare più modelli Seedance attraverso la stessa API cambiando il parametro model:

• seedream-v4-5 - 1 crediti - qualità flagship
• seedream-v3 - 1 credito - più veloce, più semplice
• seedream-5-lite - 1 credito - modalità deep thinking
• seedream-5-edit - 1 credito - editing di immagini
• seedance-2 - generazione video (endpoint diverso)

Per le applicazioni che necessitano di funzionalità di editing oltre alla generazione, seedream-5-edit gestisce l'editing di immagini basato su testo. Consulta Documentazione di Seedream 5 Edit per i dettagli.

Considerazioni sulla sicurezza

Non esporre mai le chiavi API lato client. Instrada sempre le chiamate API attraverso il tuo backend. Le chiavi esposte possono essere usate per prosciugare il saldo crediti.

Ruota le chiavi periodicamente. Se una chiave è compromessa, revocala e generane una nuova.

Registra le richieste per il debug. Includi gli ID richiesta nei tuoi log per poter correlare i fallimenti con le risposte dell'API.

Implementa quote di utilizzo per utente. Se la tua app offre la generazione AI come funzionalità, limita il consumo per utente per prevenire abusi.

Domande frequenti

Esiste un piano gratuito per l'API? I tuoi 10 crediti gratuiti di registrazione funzionano per le chiamate API. Corrispondono a 10 generazioni gratuite di Seedream v4.5 per testare l'integrazione prima di pagare.

Qual è il tempo di risposta tipico? 5-15 secondi per Seedream v4.5, a seconda della risoluzione e del carico corrente.

Posso usare l'API per prodotti commerciali? Sì. L'uso commerciale è incluso. Le immagini generate dai tuoi clienti sono di loro proprietà e possono essere utilizzate per qualsiasi scopo legittimo.

Esiste un SDK Python? Gli SDK ufficiali sono in fase di sviluppo. L'attuale API REST funziona perfettamente con le librerie HTTP standard in qualsiasi linguaggio.

Come gestisco gli errori relativi alle politiche sui contenuti? Implementa messaggi visibili all'utente che spieghino che il prompt è stato rifiutato. Registra l'errore specifico per il debug.

Cosa succede se i miei crediti si esauriscono durante una richiesta? L'API restituisce un errore 402 prima che la generazione inizi. Non vengono mai addebitati costi parziali: ottieni l'immagine completa oppure ricevi un errore.

Posso raggruppare più prompt in un'unica richiesta? Non direttamente. Usa num_images: 6 per ottenere variazioni dello stesso prompt, oppure effettua chiamate API parallele per prompt diversi.

---

L'API Seedream v4.5 offre generazione di immagini AI pronta per la produzione a prezzi per immagine prevedibili, seguendo le convenzioni REST standard. Per la maggior parte delle integrazioni, puoi passare dalla chiave API alla prima generazione funzionante in meno di 10 minuti. Per domande o prezzi a volume, contattaci tramite la dashboard del tuo account.

Inizia a integrare oggi. Ottieni la tua chiave API → | Visualizza i prezzi completi → | Leggi la guida v4.5 →