L'API di Kling 4.0 su PoYo usa un unico ID modello, kling-4.0, per text-to-video, generazione da primo/ultimo fotogramma, riferimenti visivi ed editing video. Invii una richiesta, conservi il relativo task ID e fai polling finché il task non termina. Questa guida segue lo schema attuale di PoYo, verificato il 24 ottobre 2026; i nomi dei campi di altri provider non sono intercambiabili.
Apri il playground di Kling 4.0 per provare gli input in modo visuale, oppure consulta la documentazione dell'API.
Genera il primo video con cURL
Imposta POYO_API_KEY nell'ambiente della shell, poi invia questa richiesta da cinque secondi. Tieni la credenziale sul server, non nel codice eseguito nel browser.
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-4.0",
"input": {
"prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}'
Leggi data.task_id dalla risposta JSON: un invio riuscito non equivale a un video completato. Sostituisci YOUR_TASK_ID qui sotto con quel valore:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Gli stati documentati sono not_started, running, finished e failed. A task completato, cerca in data.files il file_url del video. In caso di errore, controlla error_message e conserva il task ID per la diagnosi. Per fare polling su un task esistente non serve inviarlo di nuovo.
Un ciclo di polling in Python con limite di tempo
Installa requests ed esegui questo codice sul backend. Controlla sia gli errori HTTP sia quelli applicativi, si ferma se il task fallisce e limita l'attesa a 30 minuti. Un timeout significa che devi ricontrollare lo stesso task più tardi: ripetere automaticamente l'invio potrebbe creare un secondo job fatturabile.
import os
import time
import requests
base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") not in (0, 200):
raise RuntimeError(body.get("message") or "PoYo API error")
return body["data"]
task = checked(session.post(base + "/api/generate/submit", json={
"model": "kling-4.0",
"input": {
"prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
task = checked(session.get(
base + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "Generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", [])
if f.get("file_type") == "video"]
if not videos:
raise RuntimeError("Finished task returned no video")
print(videos[0])
break
time.sleep(10)
else:
raise TimeoutError("Check the saved task ID again: " + task_id)
Scegli la modalità di input corretta
| Obiettivo | Campi dentro input | Vincolo importante |
|---|---|---|
| Text-to-video | prompt oppure multi_prompt | Fornirne esattamente uno |
| Primo/ultimo fotogramma | image_urls con uno o due URL ordinati | Omettere aspect_ratio |
| Generazione da riferimenti | reference_image_urls, reference_video_urls oppure kling_elements | Al massimo un primo fotogramma opzionale |
| Editing di filmati | video_url e prompt | Niente image_urls, multi_prompt, reference_video_urls né aspect_ratio |
Il campo del video sorgente seleziona la modalità di editing anche se sono presenti immagini di riferimento. Nell'image-to-video, la prima immagine definisce il fotogramma iniziale; una seconda immagine definisce quello finale. Le immagini di riferimento guidano identità o stile e non hanno lo stesso significato dei fotogrammi di apertura e chiusura.
Limiti da validare prima dell'invio
La generazione supporta durate intere da 3 a 30 secondi, in 720p o 1080p. In questo schema PoYo un prompt normale è limitato a 26.000 caratteri. Ogni inquadratura di multi_prompt accetta fino a 512 caratteri; se la durata dell'inquadratura è omessa, il valore predefinito è cinque secondi. Le durate delle inquadrature devono sommare 3–30 secondi e, se specifichi una durata di primo livello, deve essere uguale a quel totale.
I riferimenti ammettono fino a 10 immagini, cinque video e sette soggetti, entro un limite complessivo di 15 asset. Un primo fotogramma conta sia nel limite delle immagini sia in quello complessivo. Ogni video di riferimento o di soggetto deve durare 3–30 secondi e la loro durata reale complessiva non può superare 30 secondi. Non arrotondare per difetto le durate per far passare la validazione a un input troppo lungo.
Capire la prima fattura
Una richiesta da cinque secondi a 720p senza input video costa 142,5 crediti, cioè $0.7125 al tasso di conversione attualmente indicato. Un input video cambia sia la tariffa sia la durata fatturabile. Consulta gli esempi di prezzo prima di stimare un flusso con video di riferimento o di editing.
Il prodotto ufficiale per creator pubblicizza controlli aggiuntivi, tra cui più keyframe. Lo schema PoYo qui espone fino a due fotogrammi di apertura e chiusura e prompt per singola inquadratura; non inviare a questo endpoint campi inventati come keyframes, seed, negative_prompt o generate_audio. Per esempi funzionanti, prosegui con la guida ai prompt e il tutorial su Omni Reference.
Domande frequenti
L'ID modello dell'API è kling-4-0? No, quello è lo slug della pagina. L'ID modello da usare nella richiesta è kling-4.0.
Posso richiedere il 4K qui? Questo endpoint PoYo al momento accetta solo 720p e 1080p. Verifica lo schema del provider invece di copiare le specifiche di marketing dell'app per creator.
Posso usare una callback? La richiesta di invio supporta un callback_url di primo livello. Consulta la documentazione aggiornata per la gestione delle callback; l'esempio di polling qui sopra non ne dipende.
Da dove comincio? Parti da una breve richiesta solo testo, salva task ID e risultato, poi aggiungi una modalità di input alla volta nel playground.