Seedance 1.0 Pro API: endpoint professionale per la generazione di video

Se stai integrando la generazione video in un prodotto, un flusso di lavoro o una pipeline, l'interfaccia web diventa prima o poi un collo di bottiglia. L'API di Seedance 1.0 Pro è lo stesso modello dell'interfaccia grafica, esposto come un endpoint REST pulito con autenticazione bearer token, prezzi prevedibili al secondo e un sistema di polling dei job semplice e diretto. Questa guida copre tutto ciò di cui hai bisogno per portarlo in produzione.

Cosa offre l'API

Tutto ciò che offre l'interfaccia web di Seedance 1.0 Pro, disponibile in modo programmatico:

• Generazione da immagine a video con URL dell'immagine sorgente
• Prompt di movimento per guidare l'animazione
• Controllo della durata da 2 a 12 secondi
• Controllo del fotogramma finale per transizioni guidate
• Blocco della camera attivabile/disattivabile
• Polling dei job per stato e URL del risultato
• Output MP4 nativo a 1080p

Utilizzala per prodotti SaaS che necessitano di generazione video integrata, pipeline interne di agenzie, flussi di lavoro di produzione batch o automazione di task video ripetitivi.

Autenticazione

Tutte le chiamate API si autenticano con un bearer token. Generane uno dalla dashboard del tuo account Arteza su arteza.ai.

Authorization: Bearer YOUR_API_KEY

Regole di sicurezza:

• Non salvare mai le chiavi API nel controllo versione
• Ruota le chiavi regolarmente
• Usa variabili d'ambiente o un gestore di segreti
• Limita le chiavi a origini specifiche, se possibile

Gli endpoint principali

Inviare un job di generazione

POST /v1/seedance-1-pro/generate

Corpo della richiesta:

{
  "source_image_url": "https://your-cdn.com/source.jpg",
  "prompt": "Slow camera push-in on the subject, warm golden hour light, shallow depth of field",
  "duration_seconds": 6,
  "camera_lock": false,
  "end_frame_url": null
}

Parametri:

Risposta:

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "created_at": "2026-04-10T12:00:00Z",
  "estimated_seconds": 90
}

Verificare lo stato del job

GET /v1/seedance-1-pro/status/{job_id}

Risposta (in corso):

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "progress": 0.45,
  "created_at": "2026-04-10T12:00:00Z"
}

Risposta (completato):

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "video_url": "https://arteza.ai/videos/abc123xyz.mp4",
  "duration_seconds": 6,
  "resolution": "1920x1080",
  "credits_charged": 144
}

Valori di stato possibili: queued, processing, completed, failed

Scaricare il risultato

Quando lo stato è completed, il campo video_url punta a un file MP4 a 1080p. Scaricalo immediatamente e salvalo nella tua infrastruttura: non fare affidamento sulla validità indefinita dell'URL.

Un esempio completo in Python

import os
import time
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1/seedance-1-pro"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def generate_video(source_image_url, prompt, duration=6, camera_lock=False, end_frame=None):
    payload = {
        "source_image_url": source_image_url,
        "prompt": prompt,
        "duration_seconds": duration,
        "camera_lock": camera_lock,
    }
    if end_frame:
        payload["end_frame_url"] = end_frame
    
    response = requests.post(f"{BASE_URL}/generate", headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()["job_id"]

def wait_for_completion(job_id, poll_interval=5, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        r = requests.get(f"{BASE_URL}/status/{job_id}", headers=HEADERS)
        r.raise_for_status()
        data = r.json()
        
        if data["status"] == "completed":
            return data["video_url"]
        if data["status"] == "failed":
            raise RuntimeError(f"Job fallito: {data.get('error', 'sconosciuto')}")
        
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Il job {job_id} non si è completato entro {timeout}s")

def download_video(url, output_path):
    response = requests.get(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)

# Utilizzo
job_id = generate_video(
    source_image_url="https://example.com/product.jpg",
    prompt="Slow camera orbit around the product, studio lighting, 6 seconds",
    duration=6,
    camera_lock=True
)

video_url = wait_for_completion(job_id)
download_video(video_url, "output.mp4")
print(f"Video salvato in output.mp4")

Un esempio completo in Node.js

import fs from 'fs';
import fetch from 'node-fetch';

const API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = 'https://api.arteza.ai/v1/seedance-1-pro';
const HEADERS = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function generateVideo(opts) {
  const response = await fetch(`${BASE_URL}/generate`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify(opts)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  return data.job_id;
}

async function waitForCompletion(jobId, { pollInterval = 5000, timeout = 300000 } = {}) {
  const start = Date.now();
  while (Date.now() - start < timeout) {
    const r = await fetch(`${BASE_URL}/status/${jobId}`, { headers: HEADERS });
    const data = await r.json();
    if (data.status === 'completed') return data.video_url;
    if (data.status === 'failed') throw new Error(`Job fallito: ${data.error}`);
    await new Promise(res => setTimeout(res, pollInterval));
  }
  throw new Error('Timeout');
}

async function downloadVideo(url, path) {
  const response = await fetch(url);
  const buffer = await response.buffer();
  fs.writeFileSync(path, buffer);
}

// Utilizzo
const jobId = await generateVideo({
  source_image_url: 'https://example.com/product.jpg',
  prompt: 'Slow camera orbit around the product, studio lighting, 6 seconds',
  duration_seconds: 6,
  camera_lock: true
});

const videoUrl = await waitForCompletion(jobId);
await downloadVideo(videoUrl, 'output.mp4');
console.log('Salvato output.mp4');

Vuoi una qualità broadcast come questa? Prova Seedance 1.0 Pro gratis →

Prezzi e fatturazione

Tariffa: circa $0,12 al secondo di video prodotto, arrotondato al credito intero superiore

I crediti vengono scalati solo in caso di generazioni riuscite. I job falliti non consumano crediti.

I piani sono gli stessi dell'interfaccia web: $5 Starter, $25 Creator, $50 Pro, $120 Studio. Consulta il pagina dei prezzi.

Limiti di frequenza e concorrenza

Gli account standard hanno limiti di frequenza adatti ai tipici carichi di integrazione. Per produzioni ad alto volume, contatta il supporto per ottenere limiti aumentati.

Indicazioni generali:

• 5-10 job simultanei è affidabile per la maggior parte degli account
• Backoff esponenziale sulle risposte HTTP 429
• Tentativi a livello di job per errori transitori (fino a 3 tentativi)
• Webhook disponibili per evitare polling eccessivo

Webhook (opzionale)

Invece del polling, registra un URL webhook nelle impostazioni del tuo account o per singola richiesta. Quando un job si completa, Arteza invia una POST al tuo URL:

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "video_url": "https://arteza.ai/videos/abc123xyz.mp4",
  "duration_seconds": 6,
  "credits_charged": 144,
  "timestamp": "2026-04-10T12:02:15Z"
}

I webhook sono firmati con una firma HMAC nell'header X-Seedance-Signature. Verifica la firma prima di considerare affidabile il payload.

Gestione degli errori

L'API restituisce i codici di stato HTTP standard:

Il corpo delle risposte di errore include un campo error con un messaggio leggibile e un campo code per la gestione programmatica.

{
  "error": "Impossibile recuperare l'URL dell'immagine sorgente",
  "code": "source_image_unreachable"
}

Requisiti dell'immagine sorgente

• Formati: PNG, JPEG, WebP
• Dimensione: fino a 10 MB per immagine
• Risoluzione: minimo 512x512, maggiore è meglio (1080p o superiore consigliato)
• Accesso URL: deve essere raggiungibile pubblicamente dai server Arteza (niente localhost, niente URL protetti da autenticazione)

Per immagini private, caricale su un URL firmato S3, CloudFront o simili, e passa l'URL firmato nella richiesta.

Buone pratiche

1. Salva gli output nella tua infrastruttura. Non fare affidamento sugli URL di Arteza nel lungo periodo.
2. Registra tutto. ID job, prompt, tempi, transizioni di stato, errori.
3. Ritenta gli errori transitori. Problemi di rete e risposte 5xx dovrebbero essere ritentati con backoff esponenziale.
4. Valida gli input in anticipo. Controlla gli URL delle immagini e i range dei parametri prima di inviare.
5. Monitora il saldo crediti. Imposta un alert quando scendi sotto una soglia.
6. Usa i webhook in produzione. Il polling va bene per carichi ridotti, ma è inefficiente su larga scala.
7. Metti in cache le generazioni identiche. Se un utente invia la stessa immagine e lo stesso prompt due volte, restituisci l'URL dalla cache.

Test e staging

Inizia ogni integrazione con il piano Starter da $5 (60 crediti al mese). È sufficiente per venti generazioni di test da 2 secondi. Costruisci e testa la tua integrazione da capo a fondo prima di passare a un piano con volumi maggiori.

Casi d'uso

• Piattaforme SaaS: consenti ai tuoi utenti di generare video dai propri asset
• E-commerce: genera video di prodotto in movimento dalle immagini del catalogo
• Settore immobiliare: automatizza la produzione di video per gli annunci a partire dalle foto
• Marketing automation: video personalizzati su larga scala
• Piattaforme di contenuti: arricchisci articoli, annunci o post social con video generati
• Strumenti video white-label: costruisci il tuo prodotto video IA sul backend di Arteza

Letture correlate

• Flussi di lavoro con elaborazione in batch
• Guida completa a Seedance 1.0 Pro
• Seedance 1.0 Pro per agenzie
• Guida all'API di Seedance 2.0

FAQ

Posso usare l'API per applicazioni commerciali? Sì, tutti gli output sono autorizzati per uso commerciale.

Cosa succede se la generazione fallisce? Nessun credito viene addebitato per le generazioni fallite.

Per quanto tempo sono ospitati i video generati? I video sono disponibili per il download per un certo intervallo di tempo dopo la generazione. Scaricali e salvali tempestivamente.

Sono disponibili librerie SDK? Sono disponibili SDK della community per Python e Node. Consulta la documentazione per sviluppatori su arteza.ai.

Posso annullare un job in corso? Sì, invia DELETE /v1/seedance-1-pro/jobs/{job_id}. I job annullati non vengono addebitati.

Come posso ottenere supporto? Contatta il supporto via email dalla dashboard del tuo account per problemi specifici all'API.

---

L'API di Seedance 1.0 Pro è la soluzione pronta per la produzione per integrare la generazione video IA a 1080p nel tuo prodotto o nella tua pipeline.

Ottieni la tua chiave API e inizia a sviluppare → con 10 crediti gratuiti inclusi alla registrazione.