canonical: https://jentic.com/apis/kubflow.ai/kubflow

# Kubflow API

The Kubflow API generates images, videos, and audio from a text prompt using the models available on a Kubflow account. A caller lists models by category, reads one model's input schema, price, and prompting guide, gets the exact credit cost of a generation before starting it, then starts the job and polls its status and result by generation id. Reference images, videos, or audio files can be uploaded first without spending generation credits, and a max_credits ceiling refuses any generation priced above it.

## For AI agents

Pick a Kubflow model, price a prompt in credits, start an image, video, or audio generation with a spending cap, and poll until the result is ready.

## Scope

Does not handle image editing pipelines, video hosting, or model training and fine-tuning. Use for pricing and running Kubflow image, video, and audio generations only.

## Capabilities

- List available Kubflow models filtered by category: image, video, or audio
- Read a single model's input schema, price, and prompting guide before writing the prompt
- Get the exact credit cost of a generation for a given model, prompt, and params without starting or charging anything
- Start an image or video generation with a model, prompt, and model-specific params, capped by max_credits
- Poll a generation by generation_id to check its status and fetch the result
- Upload a reference image, video, or audio file for use in a generation without spending generation credits

## Use cases

### Budget-Capped Image Generation

A content agent produces marketing images without overspending. It reads the chosen model's input schema and prompting guide, calls the price operation to get the exact credit cost for its prompt and params, and then starts the generation with max_credits set so Kubflow refuses the job if the price is higher than the cap.

Example prompt: Call GET `/api/v1/models/{model_id}` for the chosen image model, POST `/api/v1/generations/price` with model and prompt 'minimalist product shot of a ceramic mug on oak', then POST `/api/v1/generations` with the same body and max_credits set to the quoted price

### Image-to-Video from a Reference

To animate an existing asset, the agent uploads the reference file through the uploads operation, which spends no generation credits, then starts a video generation that points at the uploaded file through the model's params. Because generation runs asynchronously, the agent polls the generation by id until the status reports a finished result.

Example prompt: Upload a PNG with POST `/api/v1/uploads`, start a video generation with POST `/api/v1/generations` using a video model and the upload reference in params, then poll GET `/api/v1/generations/{generation_id}` until it completes

### Model Selection by Category

Kubflow exposes several models per medium. An agent filters the model list by category (image, video, or audio), reads each candidate's price and input schema, and picks the one that fits the task and budget before writing the prompt.

Example prompt: Call GET `/api/v1/models` with category 'audio', then GET `/api/v1/models/{model_id}` for each result and pick the lowest-priced model that accepts a text prompt

### AI Agent Media Generation via Jentic

An AI agent reaches Kubflow through Jentic without handling the account API key. It searches by intent, receives the generation or pricing operation with its input schema, and executes with the bearer key injected at run time, so producing an image or clip is one step inside a larger content workflow.

Example prompt: Search Jentic for 'generate an image from a prompt', load the createGeneration schema, and execute it with a Kubflow model id, a prompt, and a max_credits cap

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/generations` | Start a generation |
| POST | `/api/v1/generations/price` | Get the exact credit cost |
| GET | `/api/v1/generations/{generation_id}` | Check status and result |
| GET | `/api/v1/models` | List models |
| GET | `/api/v1/models/{model_id}` | Get a model's schema and price |
| POST | `/api/v1/uploads` | Upload a reference file |

## Key resources

- **Generations** — Price, start, and poll image, video, and audio generations
- **Models** — List models by category and read a model's input schema, price, and prompting guide
- **Uploads** — Upload reference image, video, or audio files

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 58 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 60 / 100
- **View full report:** https://jentic.com/apis/kubflow.ai/kubflow/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Kubflow by hand means sending the account key as a bearer token, pricing each generation, and polling asynchronous jobs until they finish. Through Jentic you install once, import Kubflow from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Kubflow carries the model, prompt, and params in the request body, so rules bound which operations your agent may call, not which model it uses. Limit it to the operations it needs, such as model reads and pricing, and leave out generation creation and uploads unless you add them.
- **Credential handling:** Your Kubflow API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate an image from a prompt' or 'price a video generation', and Jentic returns the matching Kubflow operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Replicate API** — Run open-source and community models for image, video, and audio
- **fal.ai API** — Hosted generative media models with fast inference
- **Runway API** — Video generation and image-to-video models
- **ElevenLabs API** — Text-to-speech and voice generation

## FAQ

### What authentication does the Kubflow API use?

Per its OpenAPI spec, the Kubflow API uses the bearerAuth scheme: your Kubflow account API key sent as a bearer token in the Authorization header. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's context.

### Can I find out what a generation costs before running it with the Kubflow API?

Yes. POST `/api/v1/generations/price` takes the same body as a real generation (model, prompt, optional category and params) and returns the exact credits it would cost without starting or charging anything. When you then start the generation, set max_credits so Kubflow refuses to start it if the price is higher.

### What are the rate limits for the Kubflow API?

The OpenAPI spec does not specify rate limits. Check https://kubflow.ai for current limits. Generations are charged in credits, so use the price operation and max_credits to control spend.

### How do I generate an image through Jentic with the Kubflow API?

Search Jentic for 'generate an image from a prompt' and it returns the createGeneration operation with its input schema. Execute POST `/api/v1/generations` with a model id from the models list and your prompt, then poll GET `/api/v1/generations/{generation_id}` for the result. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Kubflow MCP server?

You don't need an MCP server to give your agent the Kubflow API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered by intent on demand, so no extra tool definitions are loaded into the agent's context.

### Can I limit what my agent is allowed to do with the Kubflow API?

Yes. For a research or planning agent, allow only the model reads and the price operation: it can browse models and quote costs but cannot start a generation that spends credits. Add the create and status operations when you want it to generate, and set max_credits on each request to cap the cost of any single job.