# 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)
- 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 LoRAs, NO reference images.    4 pts.  ~15s
- gpt-image-2     crisp text/label rendering; 3:2 max aspect ratio.     quality low/medium
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.

## 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