Seedream 5.0 Lite API: l'endpoint di generazione immagini più veloce

REST API, autenticazione Bearer, generazione asincrona, webhook, batching nativo fino a 50 immagini per richiesta. Tutto ciò che è disponibile nell'interfaccia web di Arteza è presente anche nell'API. Ecco la documentazione completa con esempi funzionanti in Python e JavaScript pronti per essere copiati in produzione oggi stesso.

Panoramica dell'API

L'API di Seedream 5.0 Lite fornisce accesso programmatico alla pipeline di generazione immagini sulla piattaforma Arteza. Tutto ciò che è presente nell'interfaccia web, ovvero testo in immagine, deep thinking, trasferimento di stile e rendering del testo, è disponibile nell'API REST.

L'API segue le convenzioni REST con corpo delle richieste e risposte in JSON. La generazione è asincrona: si invia una richiesta, si riceve un ID attività, quindi si esegue il polling oppure si riceve un webhook al completamento.

Panoramica completa delle funzionalità nella nostra guida completa.

URL di base

https://api.arteza.ai/v1

Caratteristiche principali

Autenticazione

Autenticazione tramite Bearer token. Genera la tua chiave API dalla dashboard di Arteza sotto Impostazioni > Chiavi API.

Ottenere la chiave API

1. Registrati o accedi al tuo account Arteza
2. Vai su Impostazioni > Chiavi API
3. Clicca su Genera nuova chiave
4. Copia e conserva in modo sicuro la tua chiave (mostrata una sola volta)

Intestazione di autenticazione

Authorization: Bearer YOUR_API_KEY

Testare l'autenticazione

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.arteza.ai/v1/account/credits

Risposta:

{
  "credits_remaining": 1050,
  "tier": "starter"
}

Endpoint per immagine singola

POST /v1/images/generate

Richiesta minima

{
  "model": "seedream-5.0-lite",
  "prompt": "A serene mountain landscape at sunrise"
}

Richiesta completa

{
  "model": "seedream-5.0-lite",
  "prompt": "Professional YouTube thumbnail with text 'TOP 10 TIPS' in bold red font, excited person on left, bright blue background",
  "aspect_ratio": "16:9",
  "deep_thinking": true,
  "style": "photorealistic",
  "webhook_url": "https://your-app.com/webhook/image-complete",
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  }
}

Risposta

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "credits_remaining": 1043,
  "estimated_time_seconds": 10
}

Parametri della richiesta

Proporzioni immagine

Preset di stile

Formato della risposta

Polling dei risultati

GET /v1/images/{task_id}

In elaborazione:

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "progress": 0.65,
  "estimated_time_remaining": 5
}

Completato:

{
  "task_id": "img_abc123def456",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "image_url_webp": "https://cdn.arteza.ai/generated/img_abc123def456.webp",
  "width": 1024,
  "height": 1024,
  "model": "seedream-5.0-lite",
  "deep_thinking_used": true,
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Scadenza degli URL delle immagini

Gli URL delle immagini generate sono validi per 24 ore. Scarica e salva le immagini nel tuo storage entro questa finestra temporale.

Vuoi un testo così nitido? Prova Seedream 5.0 Lite gratis →

Esempio Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.arteza.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Invia la richiesta di generazione
response = requests.post(
    f"{BASE_URL}/images/generate",
    headers=headers,
    json={
        "model": "seedream-5.0-lite",
        "prompt": "A futuristic city skyline at sunset with flying cars",
        "aspect_ratio": "16:9",
        "deep_thinking": True
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Task inviato: {task_id}")
print(f"Crediti addebitati: {task['credits_charged']}")
print(f"Crediti rimanenti: {task['credits_remaining']}")

# Polling per il completamento
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Immagine pronta: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Generazione fallita: {result.get('error', 'Errore sconosciuto')}")
        break

    time.sleep(2)

Esempio JavaScript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.arteza.ai/v1';

async function generateImage(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/images/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedream-5.0-lite',
      prompt,
      aspect_ratio: options.aspectRatio || '1:1',
      deep_thinking: options.deepThinking || false,
      ...options
    })
  });

  const task = await response.json();
  console.log(`Task inviato: ${task.task_id}`);

  while (true) {
    const result = await fetch(
      `${BASE_URL}/images/${task.task_id}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    ).then(r => r.json());

    if (result.status === 'completed') {
      return result;
    }
    if (result.status === 'failed') {
      throw new Error(result.error || 'Generazione fallita');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Utilizzo
const result = await generateImage(
  'A cozy coffee shop interior with warm lighting',
  { aspectRatio: '16:9', deepThinking: true }
);
console.log(`URL immagine: ${result.image_url}`);

Scaricare le immagini generate

import requests

def download_image(image_url, filename):
    response = requests.get(image_url)
    with open(filename, 'wb') as f:
        f.write(response.content)
    print(f"Salvato: {filename}")

download_image(result['image_url'], 'output/my_image.png')

Endpoint per generazione batch

Per più immagini in una singola richiesta:

POST /v1/images/batch

Richiesta batch

{
  "generations": [
    {
      "prompt": "Minimalist logo design, blue circle with lightning bolt",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": true
    },
    {
      "prompt": "Professional headshot background, soft gradient",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": false
    },
    {
      "prompt": "YouTube thumbnail with text 'MUST WATCH' in red",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "16:9",
      "deep_thinking": true
    }
  ],
  "webhook_url": "https://your-app.com/webhook/batch-complete"
}

Risposta batch

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_generations": 3,
  "total_credits_charged": 21,
  "credits_remaining": 1029
}

Polling dello stato del batch

GET /v1/images/batch/{batch_id}

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "task_id": "img_001",
      "image_url": "https://cdn.arteza.ai/generated/img_001.png"
    },
    {
      "index": 1,
      "status": "completed",
      "task_id": "img_002",
      "image_url": "https://cdn.arteza.ai/generated/img_002.png"
    },
    {
      "index": 2,
      "status": "completed",
      "task_id": "img_003",
      "image_url": "https://cdn.arteza.ai/generated/img_003.png"
    }
  ]
}

Limiti del batch

Per i flussi di lavoro batch, consulta la nostra guida alla generazione in blocco.

Integrazione webhook

I webhook eliminano il polling. Quando la generazione è completata, l'API invia una richiesta POST al tuo URL.

Payload del webhook

{
  "event": "image.completed",
  "task_id": "img_abc123def456",
  "batch_id": "batch_xyz789",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Esempio di handler (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/image-complete', methods=['POST'])
def handle_image_webhook():
    data = request.json

    if data['event'] == 'image.completed':
        task_id = data['task_id']
        image_url = data['image_url']
        metadata = data.get('metadata', {})

        # Scarica l'immagine
        img_response = requests.get(image_url)
        filename = f"images/{metadata.get('project', 'default')}/{task_id}.png"
        with open(filename, 'wb') as f:
            f.write(img_response.content)

        # Aggiorna il tuo database
        update_generation_record(task_id, filename)

        print(f"Immagine salvata: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Generazione fallita: {data.get('error')}")

    return jsonify({'status': 'ok'}), 200

Sicurezza del webhook

Verifica l'autenticità del webhook tramite l'intestazione X-Seedance-Signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Modalità deep thinking

Controllata dal parametro booleano deep_thinking. Quando abilitata, il modello esegue un ragionamento aggiuntivo prima della generazione.

Quando abilitarla

Impatto sulle prestazioni

Il deep thinking aggiunge circa 3-5 secondi ma non costa crediti aggiuntivi.

Gestione degli errori

Formato della risposta di errore

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation. Required: 7, Available: 3",
    "status": 402
  }
}

Codici di errore

Strategia di retry

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/images/generate",
                headers=headers,
                json={
                    "model": "seedream-5.0-lite",
                    "prompt": prompt
                }
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Backoff esponenziale

Limiti di frequenza e best practice

Limiti di frequenza per livello

Best practice

1. Usa i webhook invece del polling - più efficiente
2. Usa il batch quando possibile - una richiesta batch vale più di 50 richieste singole
3. Backoff esponenziale - gestisci i limiti di frequenza con eleganza
4. Memorizza i risultati in cache - salva URL delle immagini e metadati nel tuo database
5. Scarica tempestivamente - gli URL delle immagini scadono dopo 24 ore
6. Monitora il saldo dei crediti - controlla credits_remaining per evitare interruzioni
7. Usa i metadati - etichetta le generazioni con ID di progetto per il tracciamento
8. Gestisci gli errori con eleganza - non ogni generazione va a buon fine

Installazione dell'SDK

Python:

pip install seedance

from seedance import SeedanceClient

client = SeedanceClient(api_key="your_key")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A beautiful sunset",
    deep_thinking=True
)

JavaScript:

npm install @seedance/sdk

import { SeedanceClient } from '@seedance/sdk';

const client = new SeedanceClient({ apiKey: 'your_key' });
const result = await client.images.generate({
    model: 'seedream-5.0-lite',
    prompt: 'A beautiful sunset',
    deepThinking: true
});

Pattern di integrazione comuni

Integrazione CMS

Genera automaticamente le immagini in evidenza alla creazione di un articolo:

@app.route('/cms/webhook/new-post', methods=['POST'])
def handle_new_post():
    post = request.json

    result = generate_image(
        prompt=f"Blog header image for article about {post['title']}, "
               f"professional editorial style, 16:9",
        aspect_ratio="16:9",
        deep_thinking=True,
        metadata={"post_id": post["id"]}
    )

    update_post_featured_image(post["id"], result["image_url"])

Immagini di prodotti per e-commerce

def generate_product_images(product):
    prompts = [
        f"Product photo of {product.name}, white background, studio lighting, 1:1",
        f"Lifestyle photo of {product.name} in use, natural setting, 16:9",
        f"Product detail close-up of {product.name}, macro photography, 1:1"
    ]

    batch = client.images.batch_generate(
        generations=[
            {"model": "seedream-5.0-lite", "prompt": p}
            for p in prompts
        ]
    )

    return batch

Automazione dei social media

def generate_weekly_social_content(brand, topics):
    generations = []
    for topic in topics:
        generations.append({
            "model": "seedream-5.0-lite",
            "prompt": f"{brand.style_prefix} {topic}, social media post, 1:1",
            "aspect_ratio": "1:1",
            "deep_thinking": True,
            "metadata": {"topic": topic, "platform": "instagram"}
        })

    return client.images.batch_generate(generations=generations)

---

L'API di Seedream 5.0 Lite è il percorso più rapido dal prompt testuale all'immagine generata, con pieno supporto per deep thinking, generazione batch e integrazione webhook.

Ottieni la tua chiave API → - 10 crediti gratuiti, genera la tua chiave da Impostazioni > Chiavi API e inizia a sviluppare in pochi minuti.