kling-api-web-app

KO | EN

gitlite — search

#cli #python #react #ai #automation #api #llm #mcp #data-science #go #ai-agents #nextjs

kling-api-web-app

★ 2 Open GitHub ↗

Full-featured web app built on the Kling AI API — text-to-video, image-to-video, Omni elements, and image generation. Complete Kling API integration example with Next.js + Convex, self-hosted.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎬 AI Gen Studio

**A self-hosted web app for the Kling AI API — full image & video generation studio**

Chat-style interface for text-to-image, text-to-video, image-to-video, and multi-element "Omni" generations — with projects, asset groups, credit tracking, and automatic archival to Google Cloud Storage.

<br/>

![Next.js](https://img.shields.io/badge/Next.js_16-black?logo=next.js&logoColor=white)
![React](https://img.shields.io/badge/React_19-087ea4?logo=react&logoColor=white)
![Convex](https://img.shields.io/badge/Convex-ee342f?logo=convex&logoColor=white)
![Tailwind CSS](https://img.shields.io/badge/Tailwind_4-38bdf8?logo=tailwindcss&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-3178c6?logo=typescript&logoColor=white)
![Vitest](https://img.shields.io/badge/Vitest-6e9f18?logo=vitest&logoColor=white)

<br/>

</div>

---

## ✨ Features

- 🖼️ **Image generation** — Kling Image (v2/v3), Omni Image, restyle, single-reference, and elements modes
- 🎥 **Video generation** — text-to-video, image-to-video, multi-image-to-video, and Omni Video with element references, first/end frame support, and motion control
- 🧩 **Elements system** — reusable characters & objects referenced with `@mention` syntax in prompts, including custom element creation with Gemini-powered auto-describe
- 📁 **Projects & asset groups** — organize generations per project, send results to shared asset groups
- 🕘 **History** — filterable gallery/list views, favorites, re-edit any past prompt with its media
- 💳 **Cost tracking** — pre-generation cost estimates, per-user/per-project credit dashboards, live account credit badge
- 🛡️ **Admin panel** — user allowlist, roles (RBAC), project management, usage reports
- 🔐 **Auth** — Google OAuth and email/password sign-in, gated by an admin-managed allowlist

## 🧱 Tech Stack

| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS 4, Radix UI, Lexical editor |
| Backend | [Convex](https://convex.dev) — database, server functions, HTTP endpoints, crons |
| Auth | [@convex-dev/auth](https://labs.convex.dev/auth) (Google + Password providers) |
| Generation API | Kling AI (JWT-signed requests, webhook callbacks) |
| Storage | Google Cloud Storage (generated results + user uploads) |
| AI utilities | Google Gemini (element auto-describe) |
| Testing | Vitest + Testing Library |

## 🏗️ Architecture

```
Browser ── Next.js (Vercel) ── Convex queries/mutations
                                    │
                                    ├── actions → Kling AI API (JWT auth)
                                    │       Kling → /api/kling-webhook (Convex HTTP action)
                                    │
                                    └── actions → Google Cloud Storage
                                            (download results, signed upload URLs)
```

1. A generation form submits a task via a Convex action, which builds the model-specific request and calls Kling with a short-lived JWT.
2. A server-side queue caps concurrent Kling slots (`KLING_CONCURRENCY`).
3. Kling calls back to the Convex HTTP endpoint `/api/kling-webhook` when a task finishes.
4. A Convex action downloads the result media into GCS so URLs never expire, then updates the task, chat message, and credit ledger.

## 🚀 Getting Started

### Prerequisites

- Node.js 20+
- A [Convex](https://convex.dev) account
- Kling AI API access key & secret
- A GCP project with a Cloud Storage bucket and a service account with `Storage Object Admin` on it
- Google OAuth client (for Google sign-in)
- Optional: a [Gemini API key](https://aistudio.google.com/apikey) for element auto-describe

### 1. Install

```bash
npm install
```

### 2. Configure environment

```bash
cp .env.example .env.local
```

Fill in `.env.local` (see comments in [.env.example](.env.example)). Server-side secrets must **also** be set on the Convex deployment:

```bash
npx convex env set AUTH_GOOGLE_ID <...>
npx convex env set AUTH_GOOGLE_SECRET <...>
npx convex env set KLING_ACCESS_KEY <...>
npx convex env set KLING_SECRET_KEY <...>
npx convex env set GCS_BUCKET_NAME <...>
npx convex env set GCS_SERVICE_ACCOUNT_KEY "$(base64 -i service-account.json)"
npx convex env set GEMINI_API_KEY <...>
```

> ⚠️ **Never commit** `.env.local`, `.env.production.local`, or any `*service-account*.json` file — they are gitignored on purpose.

### 3. Configure external services

- **Google OAuth**: add `https://<your-deployment>.convex.site/api/auth/callback/google` as an authorized redirect URI.
- **Kling webhook**: point the callback URL at `https://<your-deployment>.convex.site/api/kling-webhook`.
- **GCS CORS**: allow your app origins to `PUT` uploads (see [cors.json](cors.json) for the shape, replace the origins with your own):

```bash
  gcloud storage buckets update gs://<bucket> --cors-file=cors.json
  ```

### 4. Run

```bash
npm run dev:all   # Convex backend + Next.js frontend together (dev.sh)
```

or in two terminals:

```bash
npx convex dev    # backend
npm run dev       # frontend at http://localhost:3000
```

The first signed-in user must be allowlisted/promoted to admin directly in the Convex dashboard (`users` table); after that, user management happens in the in-app Admin panel.

## 📜 Scripts

| Command | Purpose |
|---|---|
| `npm run dev` | Next.js dev server |
| `npm run dev:backend` | Convex dev server |
| `npm run dev:all` | Both, via `dev.sh` (`dev.bat` on Windows) |
| `npm run build` | Production build |
| `npm run test` | Vitest in watch mode |
| `npm run test:run` | Run test suite once |
| `npm run lint` | ESLint |

Standalone Kling API smoke tests live in [`scripts/`](scripts) (they read `KLING_ACCESS_KEY` / `KLING_SECRET_KEY` from the environment).

## 🗂️ Project Structure

```
src/app/            Next.js routes (login, app shell, admin, project/asset-group slugs)
src/components/     UI — generation forms, history, editor, admin, ui primitives
src/hooks/          Generation hooks suite, uploads, polling
src/contexts/       Panel & upload React contexts
convex/             Backend — schema, auth, tasks, queue, webhooks, GCS, admin, RBAC
convex/kling/       Kling API client & per-model request builders
convex/gcs/         GCS download/upload actions
kling_ai_documentation*/  Kling API reference docs used during development
_bmad-output/       Planning & implementation artifacts (story-driven development log)
```

## ☁️ Deployment

The frontend deploys to [Vercel](https://vercel.com); the backend deploys with `npx convex deploy` (wired into the Vercel build via `CONVEX_DEPLOY_KEY`). Set the same environment variables on the production Convex deployment as in step 2.

## 📄 License

Private project — no license granted.

kling-api-web-app

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README