Seedance 2.0 API: Come Generare Video AI a Livello Programmato

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

Questa guida copre tutto quello che serve per integrare Seedance 2.0 nelle tue applicazioni: autenticazione, endpoint, parametri, gestione degli errori e codici di esempio pronti per la produzione in Python e JavaScript.

TL;DR - API a Prima Vista

• URL base: https://api.arteza.ai/v1
• Autenticazione: Token Bearer nell'header Authorization
• Generazione: Asincrona - invia un task, polling o webhook per il completamento
• Limiti di velocità: 60 richieste al 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: Lo stesso prezzo dinamico per secondo della web UI (~243-910 crediti per 2.0)

Quello che l'API Può Veramente Fare

Tutto quello che fa l'interfaccia web, lo fa anche l'API. Text-to-video, image-to-video, selezione del modello, controllo della durata, aspect ratio, toggle audio e accesso a ogni modello sulla piattaforma. Endpoint batch per generare molti clip contemporaneamente. Notifiche webhook in modo che non devi fare polling. Metadati personalizzati che vengono riecheggiati nei risultati per tracciare test A/B o varianti di campagna.

Modelli Supportati

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

Autenticazione in 30 Secondi

Genera una chiave API dal dashboard sotto 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 che contano:

• Non mettere mai la chiave API nel codice lato client o in repo pubblici
• Conservala in variabili d'ambiente (SEEDANCE_API_KEY)
• Ruota le chiavi periodicamente dal dashboard
• Ogni chiave eredita il saldo di crediti dell'account genitore

L'Endpoint Text-to-Video

Questo è l'endpoint che utilizzerai più spesso.

POST /v1/generate/text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Aerial shot of a coastal city at sunset, golden light reflecting off glass skyscrapers, cinematic drone footage",
  "duration": 10,
  "aspect_ratio": "16:9",
  "audio": true
}

Riferimento dei Parametri

Risposta Riuscita

{
  "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 un task_id immediatamente e fai polling per il completamento (o usa webhook).

L'Endpoint Image-to-Video

Anima un'immagine di origine 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 invece:

{
  "model": "seedance-2.0",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "The woman turns her head slowly and smiles, wind gently blowing her hair",
  "duration": 8,
  "aspect_ratio": "16:9"
}

Verifica dello Stato della Generazione

Fai polling dell'endpoint task per controllare il progresso.

GET /v1/tasks/{task_id}

Risposta In Elaborazione

{
  "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 dei video scadono in 24 ore. Scaricali e conservali sulla tua infrastruttura prontamente.

Vuoi generare output come questo a livello di programmazione? Mancano 30 secondi alla tua prima chiamata API. Ottieni la tua chiave API gratuitamente →

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"):
    """Submit a text-to-video task. Returns 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):
    """Poll until the task finishes. Returns result dict."""
    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"Generation failed: {data.get('error')}")

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


def download_video(video_url, output_path):
    """Stream the video to disk."""
    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="A cat sitting on a windowsill watching rain fall outside, cozy indoor lighting, shallow depth of field",
        duration=10,
    )
    print(f"Task submitted: {task_id}")

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

    download_video(result["video_url"], "output.mp4")
    print("Downloaded to output.mp4")

Esempio JavaScript (Node.js)

Lo stesso workflow 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(`Generation failed: ${data.error}`);
    }

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

  throw new Error(`Task ${taskId} timed out`);
}

// Usage
const taskId = await generateVideo(
  "Timelapse of a flower blooming, macro lens, soft natural lighting",
  12
);
console.log(`Task submitted: ${taskId}`);

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

Image-to-Video in Python

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

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Generate video from a local image file."""
    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 che Non Crolla

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

Forma della Risposta di Errore

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 150 credits but this generation requires 607 credits.",
    "required_credits": 607,
    "available_credits": 150
  }
}

Pattern 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"Need {error['required_credits']} credits, have {error['available_credits']}")
        # Redirect the user to /pricing
    elif status == 429:
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retry after {retry_after}s.")
    else:
        raise

Limiti di Velocità e Best Practice per la Produzione

I Limiti

Cinque Pratiche che Contano in Produzione

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

Integrazione dei Webhook

Includi webhook_url nella tua richiesta di generazione e Arteza farà POST quando il task si completa.

{
  "model": "seedance-2.0",
  "prompt": "...",
  "webhook_url": "https://yourapp.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 header X-Seedance-Signature - una firma HMAC-SHA256 del body 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 ottieni un webhook quando tutto finisce.

POST /v1/generate/batch

{
  "tasks": [
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 1 description...",
      "duration": 8
    },
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 2 description...",
      "duration": 10
    },
    {
      "type": "image-to-video",
      "model": "seedance-1.0-pro",
      "image_url": "https://example.com/product.jpg",
      "prompt": "Slow rotation revealing product details",
      "duration": 6
    }
  ],
  "webhook_url": "https://yourapp.com/api/seedance/batch-complete"
}

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

Quattro Casi di Uso Vale la Pena Costruire

1. Video Prodotto E-commerce su Larga Scala

Automatizza l'animazione del prodotto per l'intero catalogo. Fai un loop nel tuo database di prodotti, attiva una chiamata image-to-video per articolo, conserva gli URL risultanti insieme 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"Slow 360 rotation of {product['name']}, studio lighting, white background",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

Abbina questo con guida video e-commerce per i suggerimenti di flusso di lavoro.

2. Pipeline Automatizzate di Social Media

Alimenta gli argomenti di tendenza nei generatori di prompt, genera video verticale quotidiano, invia 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 di Marketing

Genera più varianti creative con tracciamento dei metadati:

variants = [
    "Product hero shot with warm lighting, luxury feel",
    "Product hero shot with bright lighting, energetic feel",
    "Product hero shot with moody lighting, premium feel",
]

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

Il campo metadata viene riecheggiato nel payload di completamento, quindi puoi instradare i risultati al bucket di campagna giusto automaticamente.

4. Applicazioni Interattive

Costruisci la generazione di video direttamente nella tua app. Un utente digita un prompt, il tuo backend chiama l'API, il webhook consegna il clip finito. L'intero ciclo richiede circa 90 secondi.

La Conclusione

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

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

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

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