API Seedance 2.0: come generare video AI in modo programmatico

Genera un video cinematografico con AI con una sola richiesta HTTP. L'API di Seedance 2.0 è la stessa pipeline di generazione utilizzata dalla piattaforma web, esposta come un'interfaccia REST pulita con autenticazione Bearer, webhook ed endpoint batch. Se sai fare una richiesta POST, puoi costruire una pipeline di generazione video.

Questa guida copre tutto ciò di cui hai bisogno per integrare Seedance 2.0 nelle tue applicazioni: autenticazione, endpoint, parametri, gestione degli errori ed esempi di codice pronti per la produzione in Python e JavaScript.

TL;DR - API in sintesi

• URL base: https://api.arteza.ai/v1
• Autenticazione: Token Bearer nell'intestazione Authorization
• Generazione: Asincrona - invia un task, usa il polling o i webhook per il completamento
• Limiti di frequenza: 60 richieste/minuto, 5 generazioni simultanee
• Modelli: Seedance 2.0, 1.0 Pro, 1.0 Lite, Seedream v3/v4.5/v5, tutti in un'unica API
• Costo in crediti: Stesso prezzo dinamico al secondo dell'interfaccia web (19-351 crediti per la 2.0)

Cosa può fare concretamente l'API

Tutto ciò che fa l'interfaccia web, lo fa anche l'API. Testo in video, immagine in video, selezione del modello, controllo della durata, rapporto d'aspetto, attivazione dell'audio e accesso a tutti i modelli sulla piattaforma. Endpoint batch per generare più clip contemporaneamente. Notifiche webhook così non devi fare polling. Metadati personalizzati restituiti nei risultati per tracciare test A/B o varianti di campagna.

Modelli supportati

Tutti i modelli utilizzano la stessa superficie API, semplicemente con identificatori diversi.

Autenticazione in 30 secondi

Genera una chiave API dalla dashboard alla voce Impostazioni > Chiavi API. Inviala come token Bearer:

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

Risposta:

{
  "credits": 2750,
  "tier": "popular"
}

Regole di sicurezza fondamentali:

• Non inserire mai la chiave API nel codice lato client o in repository pubblici
• Salvala nelle variabili d'ambiente (SEEDANCE_API_KEY)
• Ruota periodicamente le chiavi dalla dashboard
• Ogni chiave eredita il saldo di crediti dell'account principale

L'endpoint testo in video

È l'endpoint che utilizzerai di più.

POST /v1/generate/text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Ripresa aerea di una città costiera al tramonto, luce dorata che si riflette sui grattacieli di vetro, filmato cinematografico da drone",
  "duration": 10,
  "aspect_ratio": "16:9",
  "audio": true
}

Riferimento parametri

Risposta in caso di successo

{
  "task_id": "task_abc123def456",
  "status": "queued",
  "model": "seedance-2.0",
  "credits_charged": 607,
  "estimated_time": 120,
  "created_at": "2026-04-10T14:30:00Z"
}

La generazione è asincrona. Ricevi subito un task_id e fai polling per il completamento (oppure usi i webhook).

L'endpoint immagine in video

Anima un'immagine sorgente con un prompt di movimento.

POST /v1/generate/image-to-video
Content-Type: multipart/form-data

Preferisci non caricare un file? Passa un image_url al suo posto:

{
  "model": "seedance-2.0",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "La donna gira lentamente la testa e sorride, il vento le muove delicatamente i capelli",
  "duration": 8,
  "aspect_ratio": "16:9"
}

Verifica dello stato di generazione

Interroga l'endpoint del task per controllare l'avanzamento.

GET /v1/tasks/{task_id}

Risposta in corso

{
  "task_id": "task_abc123def456",
  "status": "processing",
  "progress": 65,
  "model": "seedance-2.0",
  "created_at": "2026-04-10T14:30:00Z",
  "estimated_completion": "2026-04-10T14:31:30Z"
}

Risposta completata

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "seedance-2.0",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true,
    "file_size": 8542310
  },
  "credits_charged": 607,
  "created_at": "2026-04-10T14:30:00Z",
  "completed_at": "2026-04-10T14:31:28Z"
}

Valori di stato

Gli URL video scadono dopo 24 ore. Scaricali e archivia i file sulla tua infrastruttura senza aspettare.

Vuoi generare output come questo in modo programmatico? Sei a 30 secondi dalla tua prima chiamata API. Ottieni la tua chiave API gratis →

Esempio Python pronto per la produzione

Ecco uno script completo che invia una generazione, fa polling per il completamento e scarica il risultato.

import os
import time
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def generate_video(prompt, duration=8, aspect_ratio="16:9"):
    """Invia un task testo-in-video. Restituisce il task_id."""
    response = requests.post(
        f"{BASE_URL}/generate/text-to-video",
        headers=HEADERS,
        json={
            "model": "seedance-2.0",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            "audio": True,
        },
    )
    response.raise_for_status()
    return response.json()["task_id"]


def wait_for_completion(task_id, poll_interval=5, timeout=300):
    """Fa polling finché il task non termina. Restituisce il dizionario result."""
    elapsed = 0
    while elapsed < timeout:
        response = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["result"]
        if data["status"] == "failed":
            raise RuntimeError(f"Generazione fallita: {data.get('error')}")

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Il task {task_id} non è stato completato entro {timeout}s")


def download_video(video_url, output_path):
    """Scarica il video su disco in streaming."""
    response = requests.get(video_url, stream=True)
    response.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)


if __name__ == "__main__":
    task_id = generate_video(
        prompt="Un gatto seduto sul davanzale di una finestra che guarda la pioggia fuori, illuminazione interna accogliente, profondità di campo ridotta",
        duration=10,
    )
    print(f"Task inviato: {task_id}")

    result = wait_for_completion(task_id)
    print(f"Video pronto: {result['video_url']}")

    download_video(result["video_url"], "output.mp4")
    print("Scaricato in output.mp4")

Esempio JavaScript (Node.js)

Lo stesso flusso di lavoro in Node.js moderno con fetch nativo.

const API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = "https://api.arteza.ai/v1";

async function generateVideo(prompt, duration = 8, aspectRatio = "16:9") {
  const response = await fetch(`${BASE_URL}/generate/text-to-video`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "seedance-2.0",
      prompt,
      duration,
      aspect_ratio: aspectRatio,
      audio: true,
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  const data = await response.json();
  return data.task_id;
}

async function waitForCompletion(taskId, pollMs = 5000, timeoutMs = 300000) {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const response = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const data = await response.json();

    if (data.status === "completed") return data.result;
    if (data.status === "failed") {
      throw new Error(`Generazione fallita: ${data.error}`);
    }

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

  throw new Error(`Il task ${taskId} è andato in timeout`);
}

// Utilizzo
const taskId = await generateVideo(
  "Timelapse di un fiore che sboccia, obiettivo macro, luce naturale morbida",
  12
);
console.log(`Task inviato: ${taskId}`);

const result = await waitForCompletion(taskId);
console.log(`Video pronto: ${result.video_url}`);

Da immagine a video in Python

Quando devi caricare un'immagine sorgente, usa multipart/form-data:

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Genera un video da un file immagine locale."""
    with open(image_path, "rb") as img_file:
        response = requests.post(
            f"{BASE_URL}/generate/image-to-video",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": img_file},
            data={
                "model": model,
                "prompt": prompt,
                "duration": duration,
                "aspect_ratio": "16:9",
                "audio": "true",
            },
        )
    response.raise_for_status()
    return response.json()["task_id"]

Gestione degli errori a prova di crollo

L'API utilizza i codici di stato HTTP standard con corpi di errore strutturati.

Struttura della risposta di errore

{
  "error": {
    "code": "insufficient_credits",
    "message": "Il tuo account ha 8 crediti, ma questa generazione ne richiede 24.",
    "required_credits": 24,
    "available_credits": 8
  }
}

Schema consigliato

try:
    task_id = generate_video(prompt)
except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    if status == 402:
        error = e.response.json()["error"]
        print(f"Servono {error['required_credits']} crediti, disponibili {error['available_credits']}")
        # Reindirizza l'utente a /pricing
    elif status == 429:
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Limite di frequenza raggiunto. Riprova tra {retry_after}s.")
    else:
        raise

Limiti di frequenza e buone pratiche per la produzione

I limiti

Cinque pratiche fondamentali in produzione

1. Usa i webhook, non il polling, su larga scala. Il polling spreca chiamate API. I webhook si attivano esattamente una volta.
2. Implementa il backoff esponenziale sulle risposte 429. Non riprovare immediatamente.
3. Scarica gli URL video senza aspettare. Scadono dopo 24 ore. Archiviali sulla tua CDN.
4. Valida gli input lato client. Individua problemi di lunghezza del prompt e di dimensione dei file prima di colpire l'API.
5. Controlla il saldo dei crediti prima dei batch. Un errore 402 a metà batch è fastidioso. Interroga prima /account/credits.

Integrazione dei webhook

Includi webhook_url nella tua richiesta di generazione e Arteza farà una POST quando il task sarà completato.

{
  "model": "seedance-2.0",
  "prompt": "...",
  "webhook_url": "https://tuaapp.com/api/seedance/webhook"
}

Payload del webhook

{
  "event": "task.completed",
  "task_id": "task_abc123def456",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true
  },
  "metadata": {
    "campaign_id": "summer-2026",
    "variant": "A"
  },
  "timestamp": "2026-04-10T14:31:28Z"
}

Le richieste webhook includono un'intestazione X-Seedance-Signature, una firma HMAC-SHA256 del corpo firmata con il tuo segreto webhook. Verifica sempre la firma prima di elaborare gli eventi.

Generazione batch

Quando hai bisogno di più clip, inviale come batch e ricevi un unico webhook al completamento.

POST /v1/generate/batch

{
  "tasks": [
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Descrizione scena 1...",
      "duration": 8
    },
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Descrizione scena 2...",
      "duration": 10
    },
    {
      "type": "image-to-video",
      "model": "seedance-1.0-pro",
      "image_url": "https://example.com/product.jpg",
      "prompt": "Rotazione lenta che rivela i dettagli del prodotto",
      "duration": 6
    }
  ],
  "webhook_url": "https://tuaapp.com/api/seedance/batch-complete"
}

I task in un batch vengono elaborati in parallelo fino al limite di concorrenza.

Quattro casi d'uso che vale la pena realizzare

1. Video di prodotto per l'e-commerce su larga scala

Automatizza l'animazione dei prodotti per l'intero catalogo. Scorri il database dei prodotti, lancia una chiamata immagine-in-video per ogni articolo e salva gli URL risultanti accanto al record del prodotto.

products = get_products_from_database()

for product in products:
    task_id = generate_from_image(
        image_path=product["hero_image"],
        prompt=f"Rotazione lenta a 360° di {product['name']}, illuminazione da studio, sfondo bianco",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

Abbina questo con il guida ai video per e-commerce per consigli sul flusso di lavoro.

2. Pipeline automatizzate per i social media

Alimenta i topic di tendenza nei generatori di prompt, genera video verticali giornalieri e inviali a una coda di revisione:

for topic in get_trending_topics():
    prompt = build_prompt(topic)
    task_id = generate_video(prompt, duration=6, aspect_ratio="9:16")
    queue_for_review(task_id, topic)

3. Test A/B per il marketing

Genera più varianti creative con tracciamento dei metadati:

variants = [
    "Ripresa hero del prodotto con luce calda, atmosfera di lusso",
    "Ripresa hero del prodotto con luce intensa, atmosfera energica",
    "Ripresa hero del prodotto con luce suggestiva, atmosfera premium",
]

for i, variant in enumerate(variants):
    generate_video(
        prompt=variant,
        duration=6,
        metadata={"variant": chr(65 + i), "campaign": "spring-launch"},
    )

Il campo metadata viene restituito nel payload di completamento, così puoi instradare automaticamente i risultati nel bucket di campagna corretto.

4. Applicazioni interattive

Integra la generazione video direttamente nella tua app. L'utente scrive un prompt, il tuo backend chiama l'API, il webhook consegna la clip finita. L'intero ciclo richiede circa 90 secondi.

Conclusione

L'API di Arteza è semplice da integrare e pronta per la produzione. Autenticazione lineare, semantica REST pulita, webhook per il lavoro asincrono ed endpoint batch per la scalabilità. Se hai già usato Stripe o qualsiasi altra API REST moderna, ti sentirai a casa in dieci minuti.

Per i prezzi e l'ottimizzazione dei crediti, consulta il guida ai prezzi. Per una panoramica più ampia del prodotto, leggi il guida completa a Seedance 2.0.

Pronto a iniziare a costruire? Crea il tuo account gratuito →

Continua a leggere: Guida completa a Seedance 2.0 • Guida ai prezzi • Seedance 2.0 vs Seedance 1.0 • Seedance 2.0 vs Runway Gen-4