# Directors Palette — API for AI Agents

> Directors Palette is an AI film-production studio. This file teaches an AI agent
> how to drive it over a REST API: generate cinematic images, character reference
> sheets, multi-stage recipe templates, and directed video — all from one account.

Base URL: https://directorspal.com
Full reference (read this for depth — every endpoint, the recipe system, and the
Seedance action / fight-scene directing technique): https://directorspal.com/llms-full.txt

## Auth
Every request sends a bearer token:

    Authorization: Bearer dp_your_key_here

The key is issued from a Directors Palette account. Requests run AS that account and
spend that account's points (pts). Treat the key like a password. Rate limit: 60
requests per minute per key.

## How it works: async jobs
Generation endpoints return a job immediately (HTTP 201). Poll the job until it is
done. Every response is an envelope:

    { "success": true, "data": { ... } }        // ok
    { "success": false, "error": { "code": "...", "message": "..." } }  // error

Submit → read `data.job_id` → poll `GET /api/v2/jobs/{job_id}` until `data.status`
is `completed` or `failed`. On completion the asset is in `data.result`:
`data.result.url` (a single image), `data.result.image_urls` / `urls` (multiple),
or `data.result.video_url` (video).

## Core endpoints
- GET  /api/v2/balance                  your points balance
- GET  /api/v2/models                   available image + video models and costs
- GET  /api/v2/styles                   system style guides
- GET  /api/v2/recipes                  list recipe templates (system + your own)
- GET  /api/v2/loras?library=cupcake    named krea-2 style LoRAs (the Shot Creator set)
- POST /api/v2/images/generate          generate an image
- POST /api/v2/characters/generate      character reference sheet (turnaround + expressions)
- POST /api/v2/videos/generate          animate a still image into video
- POST /api/v2/recipes/execute          run a recipe template with variables
- POST /api/v2/batch                    up to 20 jobs in one call
- GET  /api/v2/jobs/{id}                poll a job for its result

## Quickstart
1) Check balance:
   curl -H "Authorization: Bearer dp_xxx" https://directorspal.com/api/v2/balance

2) Generate an image (returns a job):
   curl -X POST https://directorspal.com/api/v2/images/generate \
     -H "Authorization: Bearer dp_xxx" -H "Content-Type: application/json" \
     -d '{"model":"nano-banana-2","prompt":"cinematic wide shot of a lighthouse in a storm, golden light breaking through dark clouds, 35mm film grain","aspect_ratio":"16:9"}'
   # → {"success":true,"data":{"job_id":"...","status":"pending","cost":10,...}}

3) Poll until done (nano-banana-2 ~60s):
   curl -H "Authorization: Bearer dp_xxx" https://directorspal.com/api/v2/jobs/JOB_ID
   # when data.status == "completed", the image is at data.result.url

## Models & cost (points per image)
- nano-banana-2   best quality, up to 14 reference images, 2K option.  10 pts (1K) / 15 pts (2K).  ~60s
- flux-2-klein-9b fast + cheap, supports url LoRAs, NO reference images. 4 pts.  ~15s
- gpt-image-2     crisp text/label rendering; 3:2 max aspect ratio.     quality low/medium
- krea-2          the Shot Creator home-render — fast local diffusion with NAMED
                  style LoRAs. 5 pts. ~15-45s. Synchronous (the POST returns the
                  finished image; no polling needed). Admin key only for now.
Character sheet = 20 pts (2 images). Video is priced per model/duration/resolution —
call GET /api/v2/models for live numbers. Always check /api/v2/balance before a batch.

## Shot Creator via API (krea-2 + named style LoRAs)
This is the same pipeline the Shot Creator UI drives. LoRAs are chosen by NAME
(not a URL) from the cupcake set, and their triggers auto-apply so the style lands.
1) Discover the LoRAs:
   curl -H "Authorization: Bearer dp_xxx" \
     "https://directorspal.com/api/v2/loras?library=cupcake"
   # → {loras:[{name:"krea2_style_jscott_campbell.safetensors", label:"J Scott Campbell",
   #            trigger_word:"In the style of J Scott Campbell.", default_strength:0.8, ...}, ...]}
2) Generate with a style LoRA (SYNCHRONOUS — the image is in the response):
   curl -X POST https://directorspal.com/api/v2/images/generate \
     -H "Authorization: Bearer dp_xxx" -H "Content-Type: application/json" \
     -d '{"model":"krea-2","prompt":"a lone gunslinger at high noon, dusty main street",
          "aspect_ratio":"16:9",
          "loras":[{"name":"krea2_style_jscott_campbell.safetensors","strength":0.8}]}'
   # → {"success":true,"data":{"job_id":"...","status":"completed","result":{"url":"https://...png"}}}
Stack up to 4 loras (order matters). Omit `strength` to use each LoRA's default.
Omit `loras` entirely for plain krea-2 text-to-image.

## Wardrobe & garment control (Shot Creator UI, Krea 2)
This one lives in the Shot Creator UI (the Shirt button), not the public API yet — but
if a user asks "can I put a specific hat/jacket on someone", the answer is yes, here:
- Turn on Wardrobe (the Shirt icon), pick a scope chip — Full outfit / Hat / Top / Jacket
  / Pants / Shoes / Accessory — attach the PERSON first and the GARMENT photo second,
  leave the prompt empty, Generate. Only the scoped garment changes; face, body, pose,
  and every other garment hold. 8 pts for a swap, 5 pts for a one-photo garment sheet.
- One photo + a scope = a clean ghost-mannequin product sheet of just that garment.
- The garment can come from a product shot OR off another person (worn extraction).
- The swap keeps the SOURCE photo's framing/pose/crop — a wide shot stays a wide shot.
Order matters: person photo first, garment photo second.

## Working tips
- Be specific: shot type + subject + action + lighting + style. Vague prompt = vague image.
- Reference images: pass public URLs in `reference_images` and say HOW to use them in the
  prompt ("same character as the reference image, now walking through rain").
- Consistency: use @tag names for saved characters so the same face recurs across shots.
- Recipes are fill-in-the-blank templates (character sheets, 9-frame cinematic grids,
  location sheets, etc.). List them, then POST /api/v2/recipes/execute with `fields`.
- Directed video, and ESPECIALLY fight / action scenes, have their own craft — read
  https://directorspal.com/llms-full.txt. Short version: on Seedance, direct the ACTION
  (call-and-response beats), not the timing; retime pacing in post.

Everything else — full request fields, error codes, the recipe catalog, and the complete
Seedance fight-choreography playbook — is in https://directorspal.com/llms-full.txt