how-tos

Przewodnik po Kling Image 4.0 API: pierwsze żądanie w cURL i Pythonie

Poyo.ai Team
9 min read
Share:

Przewodnik po Kling Image 4.0 API: pierwsze żądanie w cURL i Pythonie

Ten przewodnik po Kling Image 4.0 API prowadzi od klucza API do gotowego obrazu: jedno wywołanie cURL, pętla odpytywania w Pythonie z limitem czasu, a następnie działająca treść JSON dla każdego trybu wejścia kling-4.0-image i kling-4.0-long-image. Każdy z nich możesz najpierw wypróbować w playgroundzie Kling Image 4.0; wszystkie poniższe treści żądań są zgodne z dokumentacją PoYo.

Pierwsze żądanie do Kling Image 4.0 API w cURL

Utwórz klucz w panelu PoYo i przechowuj go na serwerze jako POYO_API_KEY. Następnie wyślij zadanie text-to-image w 2K:

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-image",
    "input": {
      "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
      "size": "16:9",
      "resolution": "2K"
    }
  }'

Odpowiedź zawiera code: 200 i data.task_id, ze status: "not_started". Wysłane zadanie to jeszcze nie gotowy obraz. Sprawdź je poleceniem:

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

Statusy to not_started, running, finished i failed. Przy finished pole data.files zawiera po jednym wpisie na obraz z file_url i file_type: "image", a data.credits_amount pokazuje koszt zadania. Przy failed odczytaj data.error_message.

Pętla odpytywania w Pythonie z limitem czasu

Ten kod działa na Twoim backendzie z requests. Sprawdza zarówno status HTTP, jak i pole code w treści odpowiedzi (błędy walidacji mogą przyjść jako HTTP 200 z code: 400), zatrzymuje się przy failed i przestaje czekać po 20 minutach bez ponownego wysyłania, bo drugie wysłanie to drugi rachunek.

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(resp):
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
    return body["data"]

def run(payload, max_wait=1200, every=10):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    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":
            return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
        time.sleep(every)
    raise TimeoutError("still running, poll task " + task_id + " again later")

urls = run({
    "model": "kling-4.0-image",
    "input": {
        "prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
        "size": "1:1",
        "resolution": "2K",
    },
})
print(urls)

Przy długich zadaniach dodaj zamiast tego "callback_url": "https://your-domain.com/poyo-hook" na najwyższym poziomie payloadu. PoYo wyśle POST z tymi samymi danymi zadania (bez opakowania code/data), gdy zadanie się zakończy lub nie powiedzie, podpisany HMAC-SHA256 w X-Webhook-Signature; dokumentacja webhooków pokazuje, jak go zweryfikować.

Image-to-image z image_urls

Przekaż od 1 do 10 publicznych URL-i HTTP(S) w image_urls. Pierwszy to @Image1, drugi @Image2, w kolejności tablicy. Nadaj każdemu rolę w prompcie i napisz, co ma pozostać bez zmian.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "resolution": "2K"
  }
}

image_urls musi być tablicą nawet dla jednego obrazu. Każdy obraz może mieć najwyżej 30 MB, co najmniej 300 px szerokości i wysokości, a stosunek szerokości do wysokości musi wynosić od 0.4 do 2.5.

Spójne obiekty z kling_elements

Element to jedna postać lub jeden obiekt pokazany z 2 do 4 ujęć, najpierw widok z przodu. Elementy wymagają co najmniej jednej pozycji w image_urls i możesz przekazać ich do 7; obrazy plus elementy są ograniczone do 10.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}

To żądanie kosztuje 13 kredytów za obraz 2K plus 1 za obraz referencyjny i 1 za element: 15 kredytów ($0.075).

Serie obrazów z enable_sequential

Przy enable_sequential: true wartość n wynosi od 2 do 10 (domyślnie 4), a model planuje obrazy jako jedną serię z tymi samymi obiektami i stylem, zwróconą w kolejności. Gdy opcja jest wyłączona, n od 1 do 9 zwraca niezależne obrazy.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}

W naszym teście w dniu premiery (produkcyjne API PoYo, 19 listopada 2026) seria 16:9 w 2K z n: 4 zwróciła cztery obrazy 2720×1536 z tym samym motocyklistą, motocyklem i strojem o świcie, w południe, o zachodzie słońca i nocą. Seria kosztuje 52 kredyty, a od wysłania do wyniku minęło około 4.9 minuty.

Długie strony WWW i e-commerce

Zmień ID modelu na kling-4.0-long-image i wybierz skill. Projekt strony WWW, opcjonalnie według referencji stylu:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
    "skill": "webpage",
    "style_image_url": "https://example.com/style-reference.png",
    "resolution": "2K"
  }
}

Strona produktu e-commerce z jednego zdjęcia produktu:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
    "skill": "ecommerce",
    "image_urls": ["https://example.com/water-bottle.png"],
    "length": "medium",
    "resolution": "1K"
  }
}

Wskazówka: określ język strony. W naszym teście angielski prompt strony WWW, który nie mówił, w jakim języku mają być teksty, zwrócił stronę z chińskim tekstem. Dodanie do promptu "All text on the page is in English." rozwiązało problem i dlatego obie powyższe treści kończą się tym zdaniem. Nasz test strony WWW w 1K zwrócił jeden obraz 1024×4257 za 110 kredytów w około 1.7–2.2 minuty.

image_urls i length należą do ecommerce; style_image_url i subject_image_url należą do webpage. Więcej o długości stron i wyjściu 8K w artykule 8K i długie obrazy z Kling Image 4.0 API.

Zapisywanie wyników

Każdy files[].file_url wskazuje na plik PNG. Skopiuj go do własnego magazynu zamiast linkować go bezpośrednio z aplikacji. Trzy rzeczy z naszego testu w dniu premiery, na które warto się przygotować:

  • Rozmiar. Jeden obraz 16:9 w 8K to PNG 10880×6144 o rozmiarze około 128 MB. Strumieniuj go na dysk zamiast ładować do pamięci i zwiększ timeout odczytu klienta.
  • Kanał alfa. Pobrane pliki były PNG w RGBA nawet dla nieprzezroczystych obrazów. Jeśli Twój pipeline, CDN lub proces druku oczekuje RGB lub JPEG, konwertuj po pobraniu.
  • Kolejność. Seria obrazów wraca w kolejności, więc indeks w files to numer kadru storyboardu lub slajdu.

Reguły walidacji do sprawdzenia przed wysłaniem

RegułaModel
prompt 1–50,000 znaków, nie same białe znakioba
image_urls 1–10 pozycji; każda 30 MB, ≥300 px, proporcje 0.4–2.5kling-4.0-image
kling_elements ≤ 7, każdy 2–4 URL-e, tylko z image_urls; obrazy + elementy ≤ 10kling-4.0-image
n 1–9 bez serii, 2–10 z enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" wymaga 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Brak dodatkowych pól (output_format, seed, negative_prompt są odrzucane)oba

Błędy, które warto obsłużyć

codeZnaczenieCo zrobić
400Nieprawidłowe parametryPopraw treść; nie ponawiaj bez zmian
401Brak lub nieprawidłowy klucz APISprawdź nagłówek
402Za mało kredytówDoładuj konto i wyślij ponownie
429Limit żądańOdczekaj i spróbuj później
500 / 502 / 503Błąd serwera lub dostawcyPonów wysłanie z backoffem

Zadanie failed nie jest rozliczane, więc ponowne wysłanie po błędzie jest bezpieczne. Ponowne wysłanie po timeoucie po Twojej stronie już nie: najpierw odpytaj ten sam task_id.

Jak liczony jest Twój pierwszy rachunek

kling-4.0-image kosztuje cenę za obraz razy liczbę obrazów, plus 1 kredyt za każdą pozycję image_urls i każdy element, raz na żądanie. Przy 1 kredyt = $0.005:

ŻądanieKredytyUSD
Pierwsze wywołanie cURL powyżej (2K, jeden obraz)13$0.065
Ten sam prompt w 8K32$0.16
Edycja z elementem powyżej (2K, 1 obraz + 1 element)15$0.075
Seria czterech obrazów 2K52$0.26
Strona WWW 1K, bez referencji110$0.55
Strona e-commerce 1K medium, 1 zdjęcie produktu95$0.475

Pełne tabele i więcej przykładów znajdziesz w artykule cennik Kling Image 4.0 API. Przegląd obu ID modeli: Czym jest Kling Image 4.0.

Najczęściej zadawane pytania

Jak wywołać Kling Image 4.0 API w Pythonie? Wyślij treść JSON metodą POST na https://api.poyo.ai/api/generate/submit za pomocą requests, odczytaj data.task_id, a następnie odpytuj /api/generate/status/{task_id} do finished i odczytaj files[].file_url. Powyższa pętla robi to z terminem i kontrolą błędów.

Jakie jest ID modelu Kling Image 4.0 API? kling-4.0-image do text-to-image, edycji i serii obrazów oraz kling-4.0-long-image do długich stron WWW i e-commerce. kling-4-0-image to tylko slug strony.

Czy Kling Image 4.0 API obsługuje webhooki? Tak. Dodaj callback_url na najwyższym poziomie żądania. PoYo wyśle podpisany POST, gdy zadanie się zakończy lub nie powiedzie.

Czy mogę otrzymać JPEG z Kling Image 4.0 API? Nie ma pola formatu wyjściowego; wyniki są w PNG. Nasze pobrane pliki były PNG w RGBA nawet dla nieprzezroczystych obrazów, więc jeśli potrzebujesz JPEG, konwertuj po swojej stronie.

Dlaczego moja długa strona WWW z Kling Image 4.0 wróciła w innym języku? Jeśli prompt nie określa języka tekstów na stronie, model może wybrać go sam. Określ go, na przykład "All text on the page is in English."

Share: