API Seedance 2.5 da immagine a video: come passare il primo frame, il primo e l'ultimo frame e le immagini di riferimento

TL;DR

• seedance-2.5/image-to-video fa muovere un'immagine, e puoi anche fornire insieme il primo e l'ultimo frame per lasciare che il modello completi il processo intermedio. Ogni clip dura 4–30 secondi e include l'audio. Apri la pagina del modello per generare online; i nuovi utenti ricevono 200 crediti alla registrazione.
• Stesso prezzo del text-to-video: 720p a $0.204 al secondo, 1080p a $0.516 al secondo. 4 secondi in 720p costano $0.816.
• Due modalità alternative: primo frame / primo e ultimo frame, oppure immagine di riferimento + audio di riferimento; non si possono combinare.

Prima guarda un risultato reale: primo e ultimo frame

Fornisci un'immagine di un «vaso vuoto» come primo frame e una di un «vaso pieno di basilico» come ultimo frame, e nel prompt descrivi solo come avviene la trasformazione:

Time-lapse growth of a basil seedling sprouting and unfurling leaves inside the terracotta pot, smooth continuous motion, soft morning light staying consistent, camera locked off, no cuts

Genera con questo prompt → (carica il tuo primo e ultimo frame, 4 secondi, 720p)

seedance-2.5/image-to-video, primo frame + ultimo frame, 720p, 4 secondi, con audio, $0.816.

Mantieni coerenti composizione, luce e posizione degli oggetti tra le due immagini e cambia solo ciò che vuoi che il video mostri (qui la pianta): così la transizione intermedia risulta fluida. La frase "soft morning light staying consistent" nel prompt serve a evitare che il modello applichi il time-lapse anche alla luce.

curl: solo il primo frame

L'uso più comune: un'immagine di prodotto o un'illustrazione, più una frase su «come si muove dopo»:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "input": {
      "prompt": "镜头缓慢推向冒着热气的咖啡杯，热气在晨光中旋转上升，轻微手持晃动",
      "first_frame_url": "https://your-cdn.example.com/coffee-cup.jpg",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Restituisce taskId:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Controlla il risultato:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando status è success, scarica il video da output[0].url.

Primo e ultimo frame: aggiungi un last_frame_url

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "同一张书桌从白天到夜晚的延时：日光渐渐变暗，台灯亮起暖光，窗外的城市灯光逐一亮起，镜头固定不动",
    "first_frame_url": "https://your-cdn.example.com/desk-day.jpg",
    "last_frame_url": "https://your-cdn.example.com/desk-night.jpg",
    "duration": 4,
    "resolution": "720p"
  }
}

• last_frame_url va usato insieme a first_frame_url.
• Se le proporzioni dell'ultimo frame differiscono da quelle del primo, l'ultimo frame viene ritagliato al centro; meglio generare entrambe le immagini con lo stesso rapporto.
• Il formato segue il primo frame; aspect_ratio ha un solo valore, adaptive, e non va passato.

Python: invio, polling, download

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="seedance-2.5/image-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "Time-lapse growth of a basil seedling sprouting and unfurling leaves, camera locked off, no cuts",
    first_frame_url="https://your-cdn.example.com/seedling-start.jpg",
    last_frame_url="https://your-cdn.example.com/seedling-grown.jpg",
    duration=4, resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Un'altra modalità: immagine di riferimento + audio di riferimento

Se non vuoi fissare un'immagine come primo frame, ma vuoi che il modello «prenda come riferimento» l'aspetto di una persona, di un prodotto o lo stile grafico, usa reference_image_urls (fino a 30 immagini) e puoi aggiungere reference_audio_urls (fino a 10 tracce) per lo stile sonoro:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "参考图里的女孩背着同款蓝色书包，走过下雨的街角，镜头跟随",
    "reference_image_urls": [
      "https://your-cdn.example.com/girl.jpg",
      "https://your-cdn.example.com/backpack.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }
}

Nota: immagine di riferimento e audio di riferimento non si possono passare insieme a first_frame_url / last_frame_url; scegli una delle due modalità.

Panoramica dei parametri

Parametro	Valore	Descrizione
prompt	stringa, obbligatorio	Descrivi azioni, inquadratura e audio; non serve ridescriover l'intera immagine
first_frame_url	URL immagine	Primo frame
last_frame_url	URL immagine	Ultimo frame, da usare con il primo
reference_image_urls	massimo 30 immagini	Non combinabile con primo/ultimo frame
reference_audio_urls	massimo 10 tracce	Non combinabile con primo/ultimo frame
duration	intero 4–30, predefinito 5	Unità: secondi
resolution	720p / 1080p, predefinito 720p
generate_audio	predefinito true	Audio e video generati insieme
output_format	mp4 / mov

Calcola il costo

Durata	720p ($0.204/secondo)	1080p ($0.516/secondo)
4 secondi	$0.816	$2.064
5 secondi	$1.02	$2.58
10 secondi	$2.04	$5.16
15 secondi	$3.06	$7.74

Primo e ultimo frame costano come il solo primo frame: il costo dipende solo da risoluzione e secondi. Per un calcolo più dettagliato vedi Prezzi dell'API Seedance 2.5.

Da tenere presente prima del rilascio

• Gli indirizzi delle immagini devono essere pubblicamente accessibili: vanno bene URL HTTP(S) o data URL; gli indirizzi di rete interna non sono raggiungibili dal modello.
• Usa i callback invece del polling: aggiungi al livello superiore della richiesta "callback": {"url": "https://tuo-dominio/hiapi/callback"} e deduplica per taskId.
• Salva subito i file: output[0].url è un link temporaneo; appena ottenuto, salvalo sul tuo storage.
• Riprova con la chiave di idempotenza: aggiungi l'header Idempotency-Key; con la stessa chiave il task viene creato una sola volta.
• Rimborso automatico in caso di errore: paghi solo per i video generati con successo.

Domande frequenti

Cosa fare se tra primo e ultimo frame compare una «dissolvenza»?

Quando le due immagini sono troppo diverse, per uno o due secondi al centro può sembrare che si sovrappongano in dissolvenza. Mantieni coerenti composizione e oggetti tra le due immagini, cambia solo il soggetto e nel prompt aggiungi "camera locked off, no cuts".

Posso fornire solo l'ultimo frame?

No, l'ultimo frame va usato insieme al primo.

Posso specificare il formato verticale?

Il formato segue il primo frame: per il verticale, carica un primo frame verticale.

Qual è la differenza tra primo frame e immagine di riferimento?

Il primo frame diventa esattamente il primo frame del video; l'immagine di riferimento serve solo al modello per riferimento di aspetto e stile, e l'inquadratura può essere ricomposta.

Hai solo il prompt e nessuna immagine? Vedi API Seedance 2.5 da testo a video. Per altri esempi di primo frame, vedi il Manuale d'uso di Seedance 2.5, oppure vai alla pagina del modello e prova a caricare un'immagine.