# Directors Palette — Full API Guide for AI Agents Directors Palette is an AI film-production studio. This document teaches an AI agent to operate it end to end over a REST API: cinematic images, character reference sheets, prompt-template "recipes", and directed video (including action/fight scenes). Base URL: https://directorspal.com Short version of this guide (quickstart only): https://directorspal.com/llms.txt ──────────────────────────────────────────────────────────────────────── 1. AUTHENTICATION & GROUND RULES ──────────────────────────────────────────────────────────────────────── Every request carries a bearer token: Authorization: Bearer dp_your_key_here - The key belongs to a Directors Palette account. Every request runs AS that account and spends that account's points (pts). Treat the key like a password. - Rate limit: 60 requests per minute per key (HTTP 429 with Retry-After if exceeded). - Content-Type: application/json on every POST. - Response envelope, always: { "success": true, "data": { ... } } { "success": false, "error": { "code": "E2xx", "message": "...", "retryable": bool } } - Points are the only currency the API cares about ("pts"). If balance < cost you get E102 insufficient points. Check GET /api/v2/balance before large jobs. ──────────────────────────────────────────────────────────────────────── 2. THE ASYNC JOB MODEL (READ THIS — everything generative is async) ──────────────────────────────────────────────────────────────────────── Generation endpoints DO NOT return the finished asset. They return a job (HTTP 201): { "success": true, "data": { "job_id": "…", "status": "pending", "type": "image", "cost": 10, "result": null, "error_message": null } } Read data.job_id, then POLL: GET /api/v2/jobs/{job_id} The poll response has the same shape. Watch data.status until it is "completed" or "failed". On completion, the finished asset is in data.result: data.result.url (a single image — this is the common case) data.result.image_urls (multiple images, e.g. batch / angles / recipe stages) data.result.urls (some multi-output jobs) data.result.video_url (video jobs) data.result.metadata (model, prompt, settings that produced it) If a field is absent, fall back to the next one. On "failed", data.error_message says why and the points are auto-refunded. Typical wait times: flux-2-klein-9b ~15s · nano-banana-2 ~60s · video 60–300s · multi-stage recipes vary. Poll every ~3–5s. You can also pass `webhook_url` on a submit to be notified instead of polling (must be a public https URL; deliveries are HMAC-signed with header X-DP-Webhook-Signature). ──────────────────────────────────────────────────────────────────────── 3. ENDPOINT REFERENCE ──────────────────────────────────────────────────────────────────────── ── GET /api/v2/balance ── Returns { balance, unit: "pts" }. No charge. ── GET /api/v2/models ── Live list of image + video models with costs. Source of truth for pricing — prefer it over the numbers printed here. ── GET /api/v2/styles ── System style guides you can attach by id (see style_id below). ── POST /api/v2/images/generate ── Generate one or more images. Returns job(s). Fields: model "nano-banana-2" (default best) | "flux-2-klein-9b" | "gpt-image-2" prompt (required) the image description aspect_ratio "16:9" (default), "1:1","9:16","4:3","3:4","21:9","3:2","2:3" reference_image a single public image URL (or) reference_images array of public image URLs (nano-banana-2 up to 14; klein = none) reference_tag attach the result to a saved canonical character/reference by @name num_images 1–5 (default 1) seed integer, for reproducibility style_id a system style-guide id from GET /api/v2/styles style a freeform style string loras [{ "path": "", "scale": 1.0 }] (flux-2-klein-9b only) webhook_url public https URL to receive completion (optional) workspace_id target workspace (optional) Example: { "model":"nano-banana-2", "prompt":"medium close-up of a weathered fisherman, golden hour sidelight, Kodak Portra 400 look", "aspect_ratio":"4:3", "num_images":1 } ── POST /api/v2/characters/generate ── Create a character reference sheet: a turnaround + an expressions sheet (2 images, 20 pts). Use these as reference_images later so the SAME character recurs across shots. Fields: name (required) character name (also usable later as an @tag) description (required) race/ethnicity, age, build, hair, clothing, distinctive features style art-style string (default "cinematic") reference_image optional real photo to base likeness on reference_images optional array style_reference optional style image URL aspect_ratio "16:9" (default) Returns two jobs; poll both. ── POST /api/v2/videos/generate ── (see section 6 for the craft) Animate a still image into a video clip. Returns a job. Fields: model "wan-2.2-5b-fast" (default) and others — see section 6 for the table prompt (required) action-first description (section 6) source_image public image URL (required for all models except seedance-1.5-pro) duration seconds (default 5) aspect_ratio "16:9" (default) resolution "480p" | "720p" (default) | "1080p" (model dependent) fps default 24 camera_fixed true locks the camera (default false) webhook_url, workspace_id optional Note: the public (Replicate-backed) video path does NOT accept reference videos or native audio, and it refuses Seedance 2.0 / 2.0-fast (they need the in-app fal path — see section 6). For photoreal human faces on the public API, use seedance-pro-fast. ── GET /api/v2/recipes · GET /api/v2/recipes/{id} ── List / read recipe templates (system recipes + your own). Each recipe has an id, name, description, and `fields` you must fill. ── POST /api/v2/recipes/execute ── (see section 5) Run a recipe. Fields: recipe_id (required) id from GET /api/v2/recipes fields object mapping FIELD_NAME → value model overrides the recipe's suggested model (recipes are model-agnostic) reference_images per-stage array of arrays, e.g. [["https://stage0-ref.jpg"]] Returns job(s); multi-stage recipes chain each stage's output into the next. ── POST /api/v2/images/upload · /api/v2/images/upload/batch ── Upload an image into your gallery (optionally set a canonical reference_tag) so you can use it as a reference later. ── POST /api/v2/batch ── Up to 20 mixed jobs in one call: { "jobs": [ { "type":"image|video|character|recipe", ... }, ... ] }. All-or-nothing balance check up front; returns a batch_id plus a job_id per job to poll. ── GET /api/v2/gallery ── your generated images. ── GET /api/v2/characters · GET|PATCH /api/v2/characters/{id} ── saved character canonicals. ── GET /api/v2/loras ── your LoRA URLs + trigger words (use with flux-2-klein-9b). ── GET /api/v2/wildcards · POST /api/v2/wildcards/expand ── random-list templating. ── GET /api/v2/jobs · GET /api/v2/jobs/{id} ── list / poll jobs. Error codes you'll see: E102 insufficient points · E203 unauthorized (bad/inactive key) · E4xx validation (bad field) · 429 rate limited. ──────────────────────────────────────────────────────────────────────── 4. IMAGE MODELS, COST & PROMPTING ──────────────────────────────────────────────────────────────────────── Models (confirm live numbers with GET /api/v2/models): nano-banana-2 best quality, up to 14 reference images, 2K option, ~60s. 10 pts (1K) / 15 pts (2K). Use for hero shots, character close-ups, title cards. flux-2-klein-9b fast + cheap (~15s), supports LoRAs, but NO reference images (text-to-image only). 4 pts. Use for crowds, establishing shots, abstract images, quick iteration. gpt-image-2 crisp text/label rendering; max aspect ratio 3:2; quality low/medium. Prompt structure that works: [Shot type] of [subject], [action/details], [lighting], [style/mood], [technical] Shot types: extreme wide (EWS) · wide (WS) · medium (MS) · medium close-up (MCU) · close-up (CU) · extreme close-up (ECU) · over-the-shoulder (OTS) · low angle (powerful) · high angle (small) · dutch (tension) · bird's-eye Lighting: golden hour · blue hour · Rembrandt · rim light · volumetric / god rays · practical (in-scene lamps) · chiaroscuro · soft diffused · harsh directional Style: cinematic + film grain + anamorphic · photorealistic 8K · oil painting · watercolor · anime cel-shaded · film noir · editorial / Vogue · documentary Color grade: teal & orange (Hollywood) · muted earth tones · monochromatic blue · pastel · warm palette · desaturated / washed out House rule (Directors Palette): NO purple, violet, indigo, or magenta in any generated asset unless the user explicitly asks. Default accents are warm (amber/gold/red). Character consistency (@tags): once you have a character sheet (or a saved canonical), reference the character by @name in the prompt AND pass its sheet URL in reference_images. Give each character ONE distinctive asymmetric detail (e.g. a scar on the LEFT cheek only) so the model can't mirror-flip them — identity stays locked across shots and video. ──────────────────────────────────────────────────────────────────────── 5. RECIPES (fill-in-the-blank templates) ──────────────────────────────────────────────────────────────────────── Recipes are pre-built, multi-stage prompt templates. List them, pick one, fill its fields. They encode the app's best workflows so an agent doesn't have to reinvent them. Flow: 1) GET /api/v2/recipes → find a recipe id + its `fields` 2) POST /api/v2/recipes/execute { "recipe_id":"", "fields":{...}, "model":"nano-banana-2" } 3) Poll the returned job(s); multi-stage recipes return image_urls per stage and a final_image_url. Template field syntax (for reading a recipe's `fields`): <> required short text (e.g. a character name) <> optional longer text <> required dropdown (must be one of the options) | (pipe) separates stages; each stage's output feeds the next as a reference Notable system recipes: - Character Sheet / Character Turnaround — consistent character references - Master Location Reference Sheet — upload 1–10 photos of ONE real place; it merges them into a single 16:9 location bible (hero view, floor plan, materials, palette, lighting), removes people, and copies the exact photographic style of the uploads - Location Reference Sheet — a location bible from a text description - 9-Frame Cinematic — a 3x3 grid of 9 camera angles of one scene (great for coverage) - Story to 9 Frames — 9 frames telling a short story sequence - Battle Rap — two performers face-to-face, configurable appearance/setting - Prop Sheet — orthographic prop reference sheet Recipes are model-agnostic: whatever `model` you pass wins over the recipe's suggestion. ──────────────────────────────────────────────────────────────────────── 6. DIRECTED VIDEO — the Seedance craft (this is where most agents fail) ──────────────────────────────────────────────────────────────────────── Directors Palette can animate a still into a directed clip via POST /api/v2/videos/generate. Doing it WELL — especially action and fight scenes — is a craft. This section is the difference between "it moved a little" and a real directed shot. 6.1 Two backends, different capabilities - Public API (this REST API) is Replicate-backed. Use models: seedance-pro-fast (face-safe, up to 12s), seedance-lite (up to 4 ref images), kling-2.5-turbo-pro, wan-2.2-5b-fast (~4s, cheapest), seedance-1.5-pro (audio). - Seedance 2.0 and 2.0-fast are the most capable (image + video references, native audio) but run on fal only and are refused by the public API (Replicate face-filters photoreal humans, error E005). For those, use the in-app Shot Animator. For photoreal faces on the public API, choose seedance-pro-fast. Video model quick table (public-API models): wan-2.2-5b-fast ~4s fixed, 480/720p, cheapest, subtle motion only seedance-pro-fast up to 12s, 480/720/1080p, face-safe, good default for action seedance-lite up to 12s, up to 4 reference images, last-frame control kling-2.5-turbo-pro 720p, premium motion quality seedance-1.5-pro up to 12s, native synced audio, start/end frame (no source_image required) 6.2 THE #1 RULE: direct the ACTION, not the timing Seedance IGNORES per-shot duration instructions. Writing "shot 2 lasts 4 seconds" does nothing; cut placement is non-deterministic. What lands with high fidelity is ACTION + CAMERA MOVE + SUBJECT STATE, described vividly. So: - Spend the prompt on action and camera language, not timing. - Pacing is a POST-production lever (retime in your editor). Don't fight the model. - Timestamp segments ("0–3s: … 3–6s: …") are useful only to ORDER beats, not to time them. 6.3 Reasoning-style prompt formula (Seedance) [Subject does a specific action], [camera movement], [scene atmosphere]. - 30–80 words. Lead with the action, then the camera, then atmosphere. - ALWAYS include a pacing/intensity adverb (slowly, rapidly, violently, deliberately) — the model can't infer speed from a still. - Use real film terms: "dolly push-in", "tracking shot", "rack focus", "crane up", "orbit", "handheld drift", "Hitchcock dolly zoom". - End on a resting state and the literal word "Hold." so the clip doesn't stop mid-motion. Example: "The warrior slowly draws their sword, cape billowing powerfully in the wind, as the camera tracks forward into a deliberate push-in. Golden-hour light shifts across the cliff face; dust drifts gently. Hold. Negative: no text overlays, no watermarks." 6.4 The Negative suffix (Seedance has no separate negative field) Append inline at the very end: "Negative: no text overlays, no captions, no watermarks, no panel dividers, no white borders, no grid lines, no UI elements." Mandatory when the source image is a contact sheet / storyboard (borders and any on-image director's notes will otherwise render into the video). Never put negatives inside the action ("no shaking") — the model ignores them there. 6.5 FIGHT & ACTION SCENES — call-and-response choreography Why AI fights fail: both characters flail in the same direction with no cause/effect — two people shadowboxing. Fix: choreograph the EXCHANGE. Every beat names one action and the exact reaction it forces. Four elements per beat, every beat: 1. ATTACK — named fighter + specific verb + intensity adverb (violently, precisely) 2. REACTION — the exact counter it forces: block / dodge / absorb / redirect / catch 3. CONSEQUENCE — visible physical proof: dust burst, skid distance, cracked rock, snapped fabric, a trench carved by sliding heels 4. CAMERA — what the camera does this beat: whip-pan, flinch, duck, push closer, hold Rules: - ONE exchange per beat. 4–5 beats max in a ~15s take (beyond that the model skips beats). - ALTERNATE initiative: whoever reacted last initiates next — that's what reads as trading momentum instead of two solo performances. - Tag fighters explicitly ("Fighter A", "Fighter B") in EVERY beat; lock full appearance up front and give each ONE asymmetric tell (mirror-flips break otherwise). - Lock screen direction ("Fighter A stays frame-left throughout") — an axis flip reads as a continuity error. - End on both fighters' named resting poses + "Hold." Weak vs strong: WEAK: "fast action fight scene" STRONG:"Fighter B ducks under the swinging pipe, pivots left, and stops in a guarded stance" WEAK: "she hits him hard" STRONG:"her knee drives into his stomach, folding him forward, boots sliding back through gravel" Powers / VFX contract (if it's a superpowered fight): every effect is physical — source → material → path → interaction with light and objects → dissipation → endpoint. Anchor energy to a body part ("a bright burst from his LEFT palm"). ONE hero effect per clip. Keep effects AROUND faces and hands, never through them (identity drifts there). Fights longer than ~15s = a sequence: end each clip on a named resting state that becomes the next clip's opening; carry injuries/damage forward as canon; escalate each clip (probing → powers → destruction → finisher). Filter safety (fights trip content filters — clarity, never evasion): "brutal fight / beatdown" → "choreographed action sequence, staged confrontation" "blood / wounds" → "non-graphic aftermath, visible fatigue, dust and torn fabric" "violent impact" → "high-energy collision, non-graphic action beat" Always end the Negative suffix with "no gore" for fight content. 6.6 Multi-shot inside one clip Seedance handles up to 3 real cuts in one clip via "Shot 1:" / "Shot 2:" / "Shot 3:" labels (one action + one camera move each). Fast tiers don't reliably honor cuts — use full seedance-2.0 (in-app) for real cuts. For an unbroken take, say "single continuous take, no cuts" and don't mix shot labels with it. 6.7 Common video mistakes - Writing per-shot durations (ignored — direct the action, retime in post). - Missing the Negative suffix (storyboard borders/labels bleed into the video). - "They fight" prompts (render as shadowboxing — use the beat grammar in 6.5). - Photoreal faces on the public API without seedance-pro-fast (Replicate face-filters → E005). - No source_image URL, or a local path instead of a public https URL. - Missing "Hold." at the end (abrupt motion at clip end looks bad). ──────────────────────────────────────────────────────────────────────── 7. A COMPLETE WORKED FLOW (character → shot → motion) ──────────────────────────────────────────────────────────────────────── 1) Balance: GET /api/v2/balance 2) Character: POST /api/v2/characters/generate { "name":"Kaya", "description":"East-African woman, late 20s, athletic build, shaved head, silver nose ring, olive field jacket, scar on the LEFT brow", "style":"cinematic" } → poll the two jobs → save the turnaround URL 3) Shot: POST /api/v2/images/generate { "model":"nano-banana-2", "prompt":"wide shot of @Kaya standing on a rain-slick rooftop at blue hour, neon haze, same character as the reference image", "reference_images":[""], "aspect_ratio":"16:9" } → poll → read data.result.url 4) Motion: POST /api/v2/videos/generate { "model":"seedance-pro-fast", "prompt":"@Kaya slowly turns to camera as the camera pushes in on a slow dolly; rain streaks through the neon glow, coat shifting in the wind. Hold. Negative: no text overlays, no watermarks.", "source_image":"", "duration":8, "resolution":"720p" } → poll → video_url ──────────────────────────────────────────────────────────────────────── 8. GETTING A KEY ──────────────────────────────────────────────────────────────────────── API access is in limited beta (admin-issued). A Directors Palette account holder gets a `dp_...` key from their account's API settings. The key spends that account's points and acts with its full permissions — keep it secret, and revoke it if it leaks. Questions this guide didn't answer? Call GET /api/v2/models and GET /api/v2/recipes — they are self-describing and always reflect what's live.