Kie.ai Python Workflow Toolkit

kie-api is a Python workflow toolkit for working with Kie.ai.

LLM quick start

If you want another LLM, agent, or wrapper to understand this repo fast, start here:

These two docs explain:

what Kie.ai is
what kie-api owns
how the request lifecycle works
how prompt presets fit in
how uploads, polling, downloads, and artifacts work
how another API system should integrate with this repo

This repo also ships a lightweight Codex plugin package under plugins/kie-ai-workflows for users who want a more guided skill-first entry point.

What is Kie.ai?

Kie.ai is a marketplace-style API platform for creative AI models. Instead of one model or one workflow, it gives you access to multiple image and video models behind one account and one API key.

Examples of model families currently covered by this repo:

Nano Banana 2
Nano Banana Pro
Seedance 2.0
Kling 2.6 text-to-video
Kling 2.6 image-to-video
Kling 3.0 text-to-video
Kling 3.0 image-to-video
Kling 3.0 motion control

Kie.ai uses a credit-based model, so different models and modes cost different amounts. This repo is built to help you avoid blind API calls by checking credits, validating inputs, and preparing media safely before generation.

Useful links:

What this repo does

This repo gives you a reusable Python layer for:

validating model-aware requests before they spend credits
uploading images, video, and audio before generation
building Kie.ai payloads with model-specific rules
resolving prompt presets for different models and request shapes
polling tasks and downloading final outputs
storing completed runs as local artifact bundles with web/thumb derivatives

It is meant for developers who want to work with KIE directly, or use a clean Python library inside a larger app.

Supported models

These descriptions are based on the current public Kie.ai model pages and live product positioning.

Nano Banana 2

Good at: fast text-to-image and image-edit workflows with strong quality for the cost
What it does: generates or edits images with native 2K output, optional 4K upscaling, good character consistency, and strong text rendering
Who it is by: Google, using Gemini 3.1 Flash Image on Kie.ai

Nano Banana Pro

Good at: higher-fidelity image generation, better prompt understanding, text rendering, and more demanding production-style image work
What it does: generates or edits higher-end images with 2K/4K output, strong typography, multi-object consistency, and better reasoning over complex visual instructions
Who it is by: Google DeepMind, using Gemini 3.0 Pro Image on Kie.ai

Kling 2.6

Good at: audio-visual video generation from text or images when you want synchronized speech, ambient sound, and sound effects in one workflow
What it does: creates short videos from text or images with native audio support and structured text-to-video or image-to-video flows
Who it is by: Kling AI on Kie.ai

Seedance 2.0

Good at: multimodal guided video generation with first-frame, first+last-frame, and mixed image/video/audio references
What it does: creates videos from plain prompts or reference-driven payloads, supports first and last frame guidance, multiple reference assets, optional audio generation, and reference-aware prompting
Who it is by: ByteDance on Kie.ai

Kling 3.0

Good at: higher-end cinematic video generation, stronger consistency, multi-shot direction, and image-to-video workflows
What it does: creates videos from text or images, supports 3 to 15 second generations, multi-shot prompting, stronger scene consistency, and native audio generation
Who it is by: Kling AI on Kie.ai

Kling 3.0 Motion Control

Good at: transferring motion or performance from a reference video onto a subject or scene defined by an image
What it does: uses a reference image plus a motion-driver video to create directed motion-controlled video output
Who it is by: Kling AI on Kie.ai

How agents use it

This toolkit is designed for agent-driven workflows. A coding agent, CLI wrapper, or application can use it to turn a user request into a real Kie.ai generation run safely.

Typical pattern:

take the user prompt and any input media
choose a model such as Nano Banana or Kling
validate the request before credits are spent
upload media first if the request includes images, video, or audio
submit the generation task
wait for completion
download the output
store a clean local run artifact bundle

flowchart TD
    A["User prompt or media input"] --> B["normalize_request()"]
    B --> C["resolve_prompt_context()"]
    C --> D["Optional LLM prompt enhancement"]
    D --> E["validate_request()"]
    E --> F["prepare_request_for_submission()"]
    F --> G["submit_prepared_request()"]
    G --> H["wait_for_task()"]
    H --> I["download_output_file()"]
    I --> J["create_run_artifact()"]

Example workflows

1. Simple image generation

Use nano-banana-2 with a prompt only:

check credits
submit a prompt-only image request
wait for completion
download the image
store the result under outputs/

2. Image edit

Use nano-banana-pro or nano-banana-2 with one or more reference images:

validate image count first
upload the images
submit the prompt plus uploaded image URLs
download the final image

3. Image to video

Use kling-3.0-i2v with one image:

create or choose a source image
upload the image first
submit a Kling prompt with the uploaded first-frame image
wait for the video task
download the final video and poster/artifacts

4. Chained run

Use one model’s output as another model’s input:

generate an image with Nano Banana
download and store it
feed that image into Kling 3.0 image-to-video
store both runs and link them through artifacts

5. Multimodal reference video

Use seedance-2.0 when you need richer video guidance:

plain text-to-video with no media
one first-frame image
first+last-frame image guidance
multimodal reference video with reference images, videos, and audio

Seedance uses role-aware media references in the runtime request model:

first_frame
last_frame
reference

First live proof path

The easiest way to prove your setup works is:

load your key
check remaining credits
run one simple Nano Banana image generation

Credit check:

. .venv/bin/activate
set -a
source .env.live
set +a
python examples/check_credit_balance.py

Then run the guarded live example:

python examples/live_run_guarded.py

The credit check is the simplest “system is connected” test. After that, the Nano Banana live example is the safest first generation test.

Supporting development

If you are already planning to use Kie.ai, using the links above is one way to support ongoing maintenance of this repo. There is no obligation, and the library works the same regardless.

Quick start

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
cp .env.example .env.live

Edit .env.live, then load it when you want to run live KIE calls:

set -a
source .env.live
set +a

Run the local suite:

python -m pytest
python scripts/sync_packaged_specs.py --check

Start with:

API key and secrets

Your KIE key belongs in KIE_API_KEY.
Do not hardcode it in Python.
Do not commit .env.live.
Use the tracked .env.example as the local template.
The repo ignores local env files so your personal key stays out of Git.

What it includes

explicit YAML model specs
editable markdown-backed prompt presets
field-level provenance for current model facts
example image and video flows that have already been tested live
typed normalization, validation, upload, submit, status, pricing, and credit models
local run artifact bundles with derivatives and append-only indexing
artifact query helpers for recent runs, filters, and latest assets
thin KIE client abstractions
public helper surface for wrapper repos
reusable request fixtures
versioned pricing snapshots and dry-run preflight gating
callback signature verification helper and credit balance probe
packaged model-spec drift guard
optional live smoke-test scaffolding

What it does not include

FastAPI routes
persistence or a job database
company auth
webhook server implementation
Slack, Discord, or Telegram delivery
hardcoded secrets

Source of truth order

live kie.ai model page
the page Playground
the page API surface
docs.kie.ai as a secondary check

When docs and live pages disagree, the live page wins and the mismatch is recorded in the spec verification_notes.

Install

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

Public usage

Upload-first is the default library contract. Any input image, video, or audio must be uploaded through prepare_request_for_submission(...) before payload build or submission.

from kie_api import (
    ArtifactDerivativeSettings,
    apply_enhanced_prompt,
    build_submission_payload,
    create_run_artifact,
    download_output_file,
    dry_run_prompt_enhancement,
    estimate_request_cost,
    get_latest_assets,
    normalize_request,
    prepare_request_for_submission,
    resolve_prompt_context,
    run_preflight,
    submit_prepared_request,
    validate_request,
    wait_for_task,
    ArtifactSource,
    PromptRecord,
    ProviderTrace,
    RunArtifactCreateRequest,
)
from kie_api.config import KieSettings
from kie_api.models import RawUserRequest

request = RawUserRequest(
    model_key="kling-3.0",
    prompt="A cinematic reveal shot.",
    images=["/absolute/path/to/start.png"],
    options={"duration": 5, "mode": "pro"},
)

normalized = normalize_request(request)
validation = validate_request(normalized)
prompt_context = resolve_prompt_context(normalized)
enhancement = dry_run_prompt_enhancement(normalized)
estimate = estimate_request_cost(normalized)
preflight = run_preflight(normalized)

if validation.state in {"ready", "ready_with_defaults", "ready_with_warning"}:
    settings = KieSettings(api_key="replace-me")
    final_request = apply_enhanced_prompt(
        normalized,
        enhancement.final_prompt_used or normalized.prompt or "",
        enhanced_prompt=enhancement.enhanced_prompt,
    )
    final_validation = validate_request(final_request)
    prepared = prepare_request_for_submission(final_validation, settings=settings)
    payload = build_submission_payload(prepared, settings=settings)
    submission = submit_prepared_request(prepared, settings=settings)
    wait_result = wait_for_task(submission.task_id, settings=settings)
    print(payload)
    print(wait_result.model_dump())
    if wait_result.final_status and wait_result.final_status.output_urls:
        download = download_output_file(
            wait_result.final_status.output_urls[0],
            "/absolute/path/to/output.bin",
            settings=settings,
        )
        print(download.model_dump())
        artifact = create_run_artifact(
            RunArtifactCreateRequest(
                status="succeeded",
                model_key=request.model_key or normalized.model_key,
                provider_model=normalized.provider_model,
                task_mode=normalized.task_mode,
                prompts=PromptRecord(
                    raw=normalized.raw_prompt,
                    enhanced=normalized.enhanced_prompt,
                    final_used=normalized.final_prompt_used,
                ),
                inputs=[
                    ArtifactSource(
                        kind="image",
                        role="reference",
                        source_path="/absolute/path/to/start.png",
                    )
                ],
                outputs=[
                    ArtifactSource(
                        kind="image",
                        role="output",
                        source_path=download.destination_path,
                    )
                ],
                provider_trace=ProviderTrace(task_id=submission.task_id),
            )
        )
        print(artifact.run_dir)
else:
    print(validation.model_dump())

print(prompt_context.model_dump())
print(enhancement.model_dump())
print(estimate.model_dump())
print(preflight.model_dump())

Wrapper-side prompt flow:

resolve_prompt_context(...) loads the model default or requested prompt preset, detects the input pattern, and renders the effective system prompt
apply_enhanced_prompt(...) sets final_prompt_used after your own LLM skill enhances the user prompt
re-run validate_request(...) after external enhancement if the prompt text changed
build_submission_payload(...) sends final_prompt_used first

Validation states

ready
ready_with_defaults
ready_with_warning
needs_input
invalid

Structured validation details include:

missing_inputs
defaulted_fields
warning_details
impossible_inputs

Specs and packaging

load_registry() prefers the repo-local specs/ tree for model specs during development and falls back to bundled package data when installed as a library.

Prompt presets and pricing snapshots are authored directly inside package resources:

src/kie_api/resources/prompt_profiles/
src/kie_api/resources/pricing/

Current default pricing snapshot:

src/kie_api/resources/pricing/2026-03-26_site_pricing_page.yaml

Refresh a candidate snapshot from KIE's public site pricing API:

. .venv/bin/activate
python scripts/refresh_site_pricing_snapshot.py --output /tmp/kie-site-pricing.yaml

Bundled model specs can be checked or synced with:

python scripts/sync_packaged_specs.py --check
python scripts/sync_packaged_specs.py

Reusable fixtures

The package exports request fixtures for integration tests:

from kie_api import REQUEST_FIXTURES, get_request_fixture

fixture = get_request_fixture("kling_3_motion_missing_video")
print(fixture.request.model_dump())

Examples

examples/check_credit_balance.py
examples/normalize_and_validate.py
examples/build_submission_payload.py
examples/dry_run_with_prompt_enhancement.py
examples/dry_run_kling_frame_guidance.py
examples/wrapper_prompt_flow.py
examples/dry_run_cost_estimate.py
examples/dry_run_preflight_gate.py
examples/run_request_fixtures.py
examples/live_run_guarded.py
examples/create_image_run_artifact.py
examples/create_video_run_artifact.py
examples/generate_derivatives_for_originals.py
examples/append_run_index.py
examples/query_artifact_runs.py
examples/rebuild_artifact_index.py
examples/create_artifact_with_custom_settings.py
examples/print_run_summary.py

Tests

Normal local test suite:

. .venv/bin/activate
python -m pytest

Optional live smoke tests:

export KIE_RUN_LIVE_SMOKE=1
export KIE_API_KEY="replace-me"
export KIE_SMOKE_UPLOAD_SOURCE_URL="https://example.com/image.png"
export KIE_SMOKE_ALLOW_SUBMIT=1
export KIE_SMOKE_SUBMIT_MODEL_KEY="nano-banana-2"
. .venv/bin/activate
python -m pytest tests/smoke -m smoke -rs

Docs

Current readiness

Library-ready for spec loading, normalization, validation, prompt preset editing, dry-run enhancement, pricing estimation, preflight gating, payload construction, and local testing
Not production-platform-ready on its own for persistence, retries, webhook serving, or full live operational guarantees

Pricing note:

estimate_request_cost(...) may return a numeric planning estimate with has_numeric_estimate=true while is_known=false when the source is KIE's public site pricing page rather than verified provider billing.

License

This repo is licensed under the MIT License. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.agents/plugins		.agents/plugins
.claude/agents		.claude/agents
.github/workflows		.github/workflows
agent_skills/codex		agent_skills/codex
docs		docs
examples		examples
plugins/kie-ai-workflows		plugins/kie-ai-workflows
scripts		scripts
skills		skills
specs		specs
src/kie_api		src/kie_api
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Kie.ai Python Workflow Toolkit

LLM quick start

What is Kie.ai?

What this repo does

Supported models

Nano Banana 2

Nano Banana Pro

Kling 2.6

Seedance 2.0

Kling 3.0

Kling 3.0 Motion Control

How agents use it

Example workflows

1. Simple image generation

2. Image edit

3. Image to video

4. Chained run

5. Multimodal reference video

First live proof path

Supporting development

Quick start

API key and secrets

What it includes

What it does not include

Source of truth order

Install

Public usage

Validation states

Specs and packaging

Reusable fixtures

Examples

Tests

Docs

Current readiness

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages