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

Se stai integrando il video in un prodotto, un workflow o una pipeline, l'interfaccia web diventa inevitabilmente un collo di bottiglia. L'API Seedance 1.0 Pro è lo stesso modello dietro l'interfaccia, esposto come un endpoint REST pulito con autenticazione bearer-token, prezzi prevedibili al secondo e polling dei job diretto. Questa guida copre tutto ciò di cui hai bisogno per distribuirlo in produzione.

Cosa fornisce l'API

Tutto ciò che offre l'interfaccia web Seedance 1.0 Pro, disponibile programmaticamente:

• Generazione da immagine a video con URL immagine sorgente
• Motion prompt per dirigere l'animazione
• Controllo durata da 2 a 12 secondi
• Controllo fotogramma finale per transizioni dirette
• Blocco fotocamera toggle
• Polling del job per stato e URL risultato
• Output MP4 a 1080p nativo

Usalo per prodotti SaaS che necessitano generazione video incorporata, pipeline di agenzie interne, workflow di produzione batch o automazione di compiti video ripetitivi.

Autenticazione

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

Authorization: Bearer YOUR_API_KEY

Regole di sicurezza:

• Non committare mai le chiavi API nel controllo sorgente
• Ruota le chiavi regolarmente
• Usa variabili d'ambiente o un gestore di segreti
• Se possibile, limita le chiavi a origini specifiche

Gli endpoint principali

Invia 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
}

Controlla 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
}

Possibili valori di stato: queued, processing, completed, failed

Scarica il risultato

Una volta che lo stato è completed, l'URL video_url punta a un file MP4 1080p. Scaricalo immediatamente e archivialo nella tua infrastruttura - non fare affidamento sul fatto che l'URL rimanga valido indefinitamente.

Un esempio Python completo

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 failed: {data.get('error', 'unknown')}")
        
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Job {job_id} did not complete within {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)

# Usalo
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 saved to output.mp4")

Un esempio Node.js completo

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 failed: ${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);
}

// Usalo
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('Saved output.mp4');

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

Prezzi e fatturazione

Tariffa: $0.24 al secondo di video in output (24 crediti/secondo)

I crediti vengono dedotti solo su generazioni riuscite. I job falliti non consumano crediti.

I pacchetti di crediti sono gli stessi dell'interfaccia web: $10 / $25 / $50 / $100. Vedi pagina prezzi.

Limiti di velocità e concorrenza

Gli account standard hanno limiti di velocità adatti a carichi di lavoro tipici di integrazione. Per produzioni ad alto volume, contatta il supporto per aumenti dei limiti.

Linee guida generali:

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

Webhook (Opzionale)

Invece di fare polling, registra un URL webhook nelle impostazioni del tuo account o per singola richiesta. Quando un job viene completato, Arteza invia un 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 prima di fidarti del payload.

Gestione degli errori

L'API restituisce codici di stato HTTP standard:

I corpi di risposta di errore includono un campo error con un messaggio leggibile dall'utente e un campo code per la gestione programmatica.

{
  "error": "Source image URL could not be fetched",
  "code": "source_image_unreachable"
}

Requisiti immagine di input

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

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

Best practice

1. Archivia gli output nella tua infrastruttura. Non fare affidamento sugli URL Arteza a lungo termine.
2. Registra tutto. ID job, prompt, tempi, transizioni di stato, errori.
3. Riprova gli errori transitori. I problemi di rete e le risposte 5xx dovrebbero riprovare con backoff esponenziale.
4. Convalida gli input presto. Controlla gli URL immagine e gli intervalli di parametri prima di inviare.
5. Monitora il saldo crediti. Avviso quando scendi sotto una soglia.
6. Usa webhook per la produzione. Il polling va bene per carichi di lavoro piccoli ma è inefficiente su larga scala.
7. Memorizza nella cache le generazioni identiche. Se un utente invia la stessa immagine + prompt due volte, restituisci l'URL nella cache.

Test e staging

Inizia ogni integrazione con il livello di crediti $10 (1.050 crediti). È sufficiente per diverse dozzine di generazioni di test. Costruisci e testa la tua integrazione end-to-end prima di impegnarti in livelli di volume più alto.

Casi di utilizzo

• Piattaforme SaaS - consenti ai tuoi utenti di generare video dai loro asset
• E-commerce - genera video di movimento prodotto da immagini di catalogo
• Real estate - automatizza la produzione video degli annunci dalle foto
• Automazione marketing - video personalizzato su larga scala
• Piattaforme di contenuti - arricchisci articoli, annunci o post social con video generato
• Strumenti video white-label - costruisci il tuo prodotto video IA sul backend Arteza

Letture correlate

• Flussi di lavoro di elaborazione batch
• Guida completa Seedance 1.0 Pro
• Seedance 1.0 Pro per agenzie
• Guida API Seedance 2.0

FAQ

Posso usare l'API per applicazioni commerciali? Sì, tutto l'output è approvato per uso commerciale.

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

Quanto tempo vengono ospitati i video generati? I video sono disponibili per il download per un periodo di tempo dopo la generazione. Scarica e archivia prontamente.

Supportate librerie SDK? SDK community per Python e Node sono disponibili. Vedi la documentazione per gli sviluppatori su arteza.ai.

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

Come ottengo supporto? Invia un'email al supporto tramite il dashboard del tuo account per problemi specifici dell'API.

---

L'API Seedance 1.0 Pro è il percorso pronto per la produzione per incorporare la generazione video IA 1080p nel tuo prodotto o pipeline.

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