API Seedream v4.5: Integra Immagini IA nella Tua App

Integrare la generazione di immagini AI nella tua app significava una volta scegliere tra tre opzioni cattive: eseguire Stable Diffusion da solo (infrastruttura costosa), pagare le tariffe per token di OpenAI (costi imprevedibili), o impegnarsi con un'API in abbonamento (capacità sprecata). L'API Seedream v4.5 è costruita diversamente - paga per immagine a $0,08, REST standard, e tempi di risposta misurati in secondi. Questa guida ti porta da zero alla prima generazione in meno di 10 minuti.

A cosa è buona l'API

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

Prodotti SaaS che permettono agli utenti di generare immagini come parte del loro flusso di lavoro - strumenti di design, piattaforme di marketing, app di creazione di contenuti.

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

Strumenti di automazione del marketing che producono elementi visivi per campagne basati su input strutturati.

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

Progetti di sviluppo e script di automazione per qualsiasi flusso di lavoro che abbia bisogno di generazione di immagini su larga scala.

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

Se il tuo caso d'uso corrisponde a uno di questi, questa guida ti farà integrare rapidamente.

Autenticazione e Come Iniziare

Passaggio 1: Ottieni una Chiave API

Iscriviti per un account Arteza se non ne hai uno. Accedi alle impostazioni del tuo account e genera una chiave API. Tratta questa chiave come una password - non eseguirne il commit in repository pubblici.

Passaggio 2: Aggiungi Crediti al Tuo Account

L'uso dell'API attinge dal saldo di crediti stesso della web. I tuoi 50 crediti gratuiti di iscrizione funzionano con le chiamate API. Per l'uso in produzione, sottoscrivi da pagina dei prezzi a partire da $10.

Passaggio 3: Fai la Tua Prima Richiesta

L'endpoint API per Seedream v4.5 è:

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

Corpo della richiesta minimo:

{
  "model": "seedream-v4-5",
  "prompt": "Una libreria accogliente al tramonto, luce calda dalla finestra",
  "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(`API error: ${response.status}`);
  }

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

// Usage
const imageUrl = await generateImage(
  'Una libreria accogliente al tramonto, luce calda dalla finestra, fotografia editoriale'
);
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']]

# Usage
urls = generate_image(
    'Una fotografia di prodotto editoriale di una tazza da caffè in ceramica, '
    'luce mattutina calda, composizione minimalista'
)
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": "Un skyline di città futuristica al tramonto, fotografia cinematografica",
    "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 di successo 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 archivia le immagini immediatamente se hai bisogno di accesso permanente.

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

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

Gestione degli Errori

L'API restituisce codici di stato HTTP standard:

Esempio di risposta di errore:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Il tuo account ha crediti insufficienti per questa richiesta",
    "credits_required": 8,
    "credits_available": 3
  }
}

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

Migliori Pratiche per l'Uso in Produzione

Limitazione della Velocità

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

Implementa backoff esponenziale su 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("Max retries exceeded")

Gestione dei Crediti

Monitora il campo credits_remaining in ogni risposta. Configura avvisi quando il saldo scende al di sotto di una soglia in modo da poter effettuare il rifornimento prima che il traffico di produzione raggiunga zero crediti.

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Low credit warning: {remaining} credits')

Gestione Asincrona

Per le applicazioni rivolte all'utente, tratta la generazione di immagini come asincrona. Non bloccare il thread dell'interfaccia utente su una chiamata API di 5-15 secondi. Modelli:

• Restituisci un ID di lavoro immediatamente, esegui il polling per il completamento
• Utilizza webhook (se supportati) per notifiche di completamento
• Genera in modo speculativo in background e memorizza nella cache i risultati

Caching

Le immagini generate sono deterministiche dato lo stesso prompt e seed. Memorizza nella cache aggressivamente per 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 del Prompt

Se la tua app espone i prompt agli utenti finali, implementa il filtraggio dei contenuti prima di inviare all'API. Arteza ha politiche sui contenuti - i prompt che le violano restituiranno errori, sprecando crediti e creando fallimenti rivolti agli utenti.

Prezzi per l'Utilizzo dell'API

L'utilizzo dell'API attinge dal saldo dei crediti del tuo account alla stessa velocità dell'utilizzo web.

I crediti provengono da livelli di prezzo indipendentemente dal fatto che li usi tramite web o API:

• Starter: $10 = 1.050 crediti = ~131 immagini
• Popular: $25 = 2.750 crediti = ~343 immagini
• Creator: $50 = 5.750 crediti = ~718 immagini
• Studio: $100 = 12.000 crediti = ~1.500 immagini

I clienti con volume più elevato possono contattare il supporto per i prezzi basati sul volume per l'utilizzo sostenuto superiore a 100.000 immagini/mese.

Combinazione con Altri Modelli Arteza

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

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

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

Considerazioni di Sicurezza

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

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

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

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

Domande Frequenti

C'è un livello gratuito per l'API? I tuoi 50 crediti di iscrizione funzionano sulle chiamate API. Questo è 6 generazioni Seedream v4.5 gratis 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 utilizzare l'API per prodotti commerciali? Sì. L'utilizzo commerciale è incluso. Le immagini generate dai tuoi clienti sono loro per usarle per qualsiasi scopo legittimo.

C'è un SDK Python? Gli SDK ufficiali sono in sviluppo. L'attuale API REST funziona pulitamente con librerie HTTP standard in qualsiasi linguaggio.

Come gestisco gli errori di politica sui contenuti? Implementa messaggi rivolti agli utenti che spieghino che il prompt è stato rifiutato. Registra l'errore specifico per il debugging.

Cosa succede se i miei crediti si esauriscono durante una richiesta? L'API restituisce un errore 402 prima che inizi la generazione. Le spese parziali non si verificano mai - o ottieni l'immagine completa o ricevi un errore.

Posso raggruppare più prompt in una sola richiesta? Non direttamente. Usa num_images: 6 per ottenere variazioni dello stesso prompt, oppure fai chiamate API parallele per prompt diversi.

---

L'API Seedream v4.5 ti offre la generazione di immagini AI pronta per la produzione a prezzi prevedibili per immagine con convenzioni REST standard. Per la maggior parte delle integrazioni, puoi passare da una chiave API alla prima generazione funzionante in meno di 10 minuti. Per domande o prezzi per volume, contatta attraverso il pannello del tuo account.

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