Give an agent
your character.
One stateless call returns your character in any scene you describe — the same references, the same prompt contract the app itself uses. The model can generate and read; it cannot change who your character is.
- List your characters and read a profile
- Generate a scene, or a transparent cutout with a real alpha channel
- Read the generation history it and you have produced
- Change a character's identity, notes, or references
- Approve, reject, or mark a render final
- Spend past your credit balance, or reach another account
Every call is charged and logged to the same ledger as the app, so an agent working overnight is as auditable as a click. Identity edits stay in the product on purpose — an agent that can redefine the character can undo the only thing this tool sells.
Known limits.
Stated here because finding these out one credit at a time is the worst way to learn them.
- One character per image. There is no way to generate two characters interacting — this is architectural, not a setting.
- Text inside a render is unreliable. Ask for a blank sign or screen and set real type over it in your layout.
- A cutout is the character and what they are holding — no environment, by definition of the keying.
- Generation is sequential and shares a rate limit. Under load you will see waits of 30–60 seconds rather than failures.
Get your key.
The owner key authenticates automation. Treat it like a password.
cat ~/.kyara/config.json It holds apiKey, and the file should be chmod 600. The key carries your whole library, so it never belongs in a repo, a prompt you paste publicly, or a client-side bundle.
Generate a scene.
These two fields fill both snippets below.
KEY=$(python3 -c "import json;print(json.load(open('$HOME/.kyara/config.json'))['apiKey'])")
curl -s -X POST https://kyara-api-788053109579.us-central1.run.app/api/characters/rue/scene \
-H "x-api-key: $KEY" \
-H 'Content-Type: application/json' \
-d '{"prompt":"slumped at her desk at 2am, three empty coffee cups","mode":"scene"}'KEY=$(python3 -c "import json;print(json.load(open('$HOME/.kyara/config.json'))['apiKey'])")
curl -s -X POST https://kyara-api-788053109579.us-central1.run.app/api/characters/rue/scene \
-H "x-api-key: $KEY" \
-H 'Content-Type: application/json' \
-d '{"prompt":"slumped at her desk at 2am, three empty coffee cups","mode":"cutout"}'Brief the model.
Paste this at the top of the session. It states what the agent may do and how to write a prompt that does not fight the references.
You can generate images of a saved character through the Kyara Lab API.
THE CONTRACT
- POST /api/characters/<slug>/scene with {"prompt": "...", "mode": "scene"|"cutout"}.
- Authenticate with the owner key in the x-api-key header. Never print the key.
- It returns the absolute path of the PNG it wrote. mode "cutout" returns a
transparent PNG suitable for UI work.
- A 429 includes retryAfter in seconds. Wait that long, then retry. Do not
retry faster and do not parallelise — generation is sequential by design.
WHAT A CALL COSTS
- Every call spends one credit of real money and is written to the usage
ledger. There is no free retry. Ask before generating variations in bulk.
HOW TO WRITE THE PROMPT
- Describe the situation, not the character. The references already carry the
face, hair, build, outfit and palette; repeating them fights the model and
produces drift.
- Good: "slumped at her desk at 2am, three empty coffee cups, lit by monitor glow".
- Bad: "a woman with curly black hair and glasses in a green hoodie sitting at a desk".
- Name the shot when it matters: full body, medium shot, close-up, from behind.
- For a cutout, describe the pose and nothing about the background. The
backdrop is keyed out; anything you ask for there is wasted or leaks.
WHAT YOU CANNOT DO
- You cannot change the character's identity, notes, or references.
- You cannot approve, reject, or mark anything final. A person does that.
- You cannot reach any account other than the key's owner.