Kling 4.0 API: przewodnik po pierwszym wideo z Pythonem i cURL

Kling 4.0 API w PoYo używa jednego ID modelu, kling-4.0, do generowania wideo z tekstu, z pierwszej i ostatniej klatki, z referencji wizualnych oraz do edycji wideo. Wyślij żądanie, zachowaj ID zadania i odpytuj o status, aż zadanie się zakończy. Ten przewodnik opiera się na aktualnym schemacie PoYo, sprawdzonym 24 października 2026; nazwy pól innego dostawcy nie są wymienne.

Otwórz playground Kling 4.0, aby wypróbować wejścia wizualnie, albo zajrzyj do dokumentacji API.

Wygeneruj pierwsze wideo za pomocą cURL

Ustaw POYO_API_KEY w zmiennych środowiskowych powłoki, a potem wyślij to pięciosekundowe żądanie. Klucz trzymaj na serwerze, a nie w kodzie przeglądarki.

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"
    }
  }'

Odczytaj data.task_id z odpowiedzi JSON; pomyślne wysłanie żądania nie oznacza jeszcze gotowego wideo. Zastąp poniżej YOUR_TASK_ID tą wartością:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Udokumentowane statusy to not_started, running, finished i failed. Po zakończeniu sprawdź w data.files adres file_url wideo. W razie niepowodzenia sprawdź error_message i zachowaj ID zadania do diagnozy. Odpytywanie istniejącego zadania nie wymaga ponownego wysyłania żądania.

Ograniczona pętla odpytywania w Pythonie

Zainstaluj requests i uruchom to na swoim backendzie. Kod sprawdza zarówno błędy HTTP, jak i błędy aplikacji, przerywa działanie przy nieudanym zadaniu i ogranicza oczekiwanie do 30 minut. Przekroczenie czasu oznacza, że to samo zadanie trzeba sprawdzić później; automatyczne ponowne wysłanie żądania mogłoby utworzyć drugie, płatne zadanie.

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)

Wybierz właściwy tryb wejścia

Pole z wideo źródłowym wybiera tryb edycji nawet wtedy, gdy podano też obrazy referencyjne. W trybie obraz na wideo pierwszy obraz wyznacza klatkę początkową, a drugi - klatkę końcową. Obrazy referencyjne kierują tożsamością lub stylem i nie znaczą tego samego co klatki graniczne.

Limity, które warto sprawdzić przed wysłaniem

Generowanie obsługuje całkowite czasy trwania od 3 do 30 sekund, w 720p lub 1080p. Zwykły prompt jest w tym schemacie PoYo ograniczony do 26 000 znaków. Każde ujęcie w multi_prompt przyjmuje do 512 znaków; pominięty czas trwania ujęcia domyślnie wynosi pięć sekund. Czasy trwania ujęć muszą w sumie dawać 3-30 sekund, a jawnie podany czas trwania na najwyższym poziomie musi być równy tej sumie.

Referencje pozwalają na maksymalnie 10 obrazów, pięć filmów i siedem postaci lub obiektów, przy łącznym limicie 15 zasobów. Pierwsza klatka wlicza się zarówno do limitu obrazów, jak i do limitu ogólnego. Każdy film referencyjny lub film obiektu musi trwać 3-30 sekund; ich łączny rzeczywisty czas nie może przekroczyć 30 sekund. Nie zaokrąglaj czasów w dół, żeby zbyt duże wejście przeszło walidację.

Zrozum pierwszy rachunek

Pięciosekundowe żądanie w 720p bez wideo na wejściu kosztuje 142,5 kredytu, czyli $0.7125 według aktualnie podanego przelicznika. Wideo na wejściu zmienia zarówno stawkę, jak i rozliczany czas trwania. Zanim oszacujesz workflow z filmem referencyjnym lub edycją, zobacz przykłady cen.

Oficjalny produkt dla twórców reklamuje dodatkowe opcje sterowania, w tym wiele klatek kluczowych. Schemat PoYo udostępnia tu do dwóch klatek granicznych i prompty dla poszczególnych ujęć; nie wysyłaj do tego endpointu wymyślonych pól keyframes, seed, negative_prompt ani generate_audio. Przykłady, które działają, znajdziesz w przewodniku po promptach i poradniku Omni Reference.

Najczęstsze pytania

Czy ID modelu w API to kling-4-0? Nie. To slug strony. ID modelu w żądaniu to kling-4.0.

Czy mogę tu zamówić 4K? Ten endpoint PoYo obecnie akceptuje tylko 720p i 1080p. Sprawdzaj schemat dostawcy, zamiast kopiować specyfikacje marketingowe z aplikacji dla twórców.

Czy mogę użyć callbacku? Żądanie wysyłania obsługuje callback_url na najwyższym poziomie. Obsługę callbacku sprawdź w aktualnej dokumentacji; powyższy przykład z odpytywaniem od niego nie zależy.

Od czego zacząć? Najpierw użyj krótkiego żądania tylko z tekstem, zapisz jego ID zadania i wynik, a potem dodawaj po jednym typie wejścia w playground.