Keou Studio documentation

What Keou is

Keou turns one raw product photograph into a finished commercial campaign: images, cinematic video, voice-over, sound design, and every delivery format your channels need. It is a full studio, not a wrapper around a generation endpoint.

The thing that makes it useful for product work is that the product itself is pixel-locked. The scene around it is generated; the shape, text, labels and logos on the object are not redrawn. That is the difference between a usable packshot and an image that merely resembles your product.

Three ways to run it

What it does

Install

What you need

From source

# clone and install
git clone https://github.com/kanakytech/keou.git
cd keou
npm ci
cp .env.example .env

# four values matter, not two
DATABASE_URL=postgresql://…
JWT_SECRET=…                  # openssl rand -hex 32
ADMIN_EMAIL=you@example.com   # seeds your account on first boot
ADMIN_PASSWORD=…              # 12+ chars

npm start

Open http://localhost:3401 and sign in. Migrations run on boot.

With Docker

docker build -t keou .
docker run -p 3401:3401 --env-file .env keou

The image is multi-stage, runs as a non-root user, and exposes a healthcheck on /health. It sets NODE_ENV=production, which turns Postgres TLS on — add DATABASE_SSL=0 to your .env if your database is local and speaks plain TCP.

On Railway

1. Create the project

   New project → Deploy from GitHub → this repository, or your fork of it.

2. Add PostgreSQL

   Add a PostgreSQL service in the same project. Railway injects DATABASE_URL for you — do not set it by hand.

3. Set the variables

   JWT_SECRET, and the four R2_* values if you are using storage.

4. Deploy

   railway.json and the healthcheck are already in the repository. Enable auto-deploy on main to receive upstream updates automatically.

Your first visual

1. Get a provider key

   Sign up at kie.ai — they give you free credits. Copy the long API key string.

2. Paste it in the key bar

   Top of the studio. Press Save. It is written to this browser's localStorage and nowhere else.

3. Drop a product photo

   Any reasonably lit shot works. A plain background helps but is not required — the scene gets rebuilt anyway.

4. Describe the scene, not the product

   Say where it sits and how it is lit: "on wet volcanic stone at dawn, sea mist behind, low warm sun from the left". Do not describe the object — it is already in the photo and it will not be redrawn.

5. Generate, then refine

   Use Polish to fix a detail, Remix for a different direction, Adapt for other ratios, Pack for the multi-format set.

Architecture

An Express server, a PostgreSQL database, an object store, and a background poller. No queue broker, no microservices, no build step for the frontend — the pages are plain HTML and vanilla JavaScript served statically.

What happens during a generation

Where things live in the repository

Configuration

Copy .env.example to .env. Two values are mandatory; everything else has a working default.

Required

Storage — required to upload

Optional

Running it in production

Before you expose it

• Set a real JWT_SECRET — 32 bytes of randomness, not a word.
• Terminate TLS in front — the app trusts one proxy hop (trust proxy: 1), which is what rate limiting and secure cookies rely on. Put exactly one reverse proxy in front, no more.
• Set ADMIN_EMAIL and ADMIN_PASSWORD for the first boot, then change the password and remove them.
• Configure storage. See the warning above.

Scaling to more than one instance

The app is stateless apart from PostgreSQL and R2, so you can run several replicas behind a load balancer. One thing does not parallelise: the poller.

Staying up to date

The public repository is rebuilt from the Keou core on every change — engine improvements, provider updates and security fixes land as commits on main.

Keys & security

Where your provider key lives

In your browser's localStorage, and nowhere else. Each generation request carries it in an X-Provider-Key header; the server uses it for that single provider call and never writes it to disk, to the database, or to logs.

Account security

Programmatic access

# 1 — sign in
TOKEN=$(curl -s -X POST https://your-host/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' | jq -r .accessToken)

# 2 — mint a long-lived key (shown once)
curl -s -X POST https://your-host/api/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"ci-pipeline"}'

HTTP API

Everything is under /api. The generation routes sit directly on /api — /api/video, not /api/generate/video. Authenticated routes accept Authorization: Bearer <token> — either a session token from /api/auth/login or a long-lived key from /api/keys.

Generation

Content and organisation

Account and team

A generation, end to end

# upload a source image (field name is "image")
curl -s -X POST https://your-host/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@bottle.jpg"

# generate — your provider key rides the request, it is never stored
curl -s -X POST https://your-host/api/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Provider-Key: $KIE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"imgUrl":"…","creativeDirection":"on wet volcanic stone at dawn"}'

# poll until it lands — pass generationId so the result is persisted
curl -s "https://your-host/api/status/image/$TASK?generationId=$GEN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Provider-Key: $KIE_KEY"

The assistant

A chat agent with the entire toolset wired in as tools: it can generate, polish, remix, adapt, build packs, produce voice and sound, and file the results under the right client — from a sentence.

It runs on your own Anthropic key, set either as ANTHROPIC_API_KEY or from Settings → API Keys inside the app. Without a key the chat returns a clear error and nothing else is affected.

Troubleshooting

Licence & use

MIT. In plain terms: run it, modify it, self-host it, fork it, use it for client work, charge for that work, and keep the money. You do not owe us a licence fee, a revenue share, or a mention.

Attribution is appreciated and not required.

Custom builds

Generic software solves the generic eighty per cent. The remaining twenty — your naming rules, your catalogue schema, your approval chain — is where the hours actually go. Closing that gap is the work we sell, scoped with you rather than priced off a list.

3D models, music, sound design, editing, VFX. Features that don't exist yet, integration with the systems you already run, deployment on your own ground, your own models and endpoints, and a handover meant to make you independent of us. You own what we write, under the same MIT terms.