@sogni-ai/sogni-intelligence-client 2.1.0

package/dist-esm/schemas/storyboards/storyboard-planning-contract.schema.json

@@ -0,0 +1,108 @@
+{
+  "title": "storyboard planning contract",
+  "schemaVersion": "2026-05-12.1",
+  "description": "Typed planner payload for storyboard layout and text-rendering decisions. Renderable visible text is intentionally separate from non-renderable production metadata labels.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "source", "layout", "scenes", "endCard", "metadataLabels"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "storyboard-planning-contract/v1"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["llm_schema", "assistant_metadata", "user_schema", "fallback_text"]
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "storyboardCanvasAspectRatio", "storyboardCellAspectRatio", "targetVideoAspectRatio", "boardDimensions"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["llm_schema", "assistant_metadata", "user_schema", "fallback_text"]
+        },
+        "storyboardCanvasAspectRatio": {
+          "type": "string",
+          "description": "Aspect ratio for the composite storyboard sheet/page, such as 16:9 or 9:16."
+        },
+        "storyboardCellAspectRatio": {
+          "type": "string",
+          "description": "Aspect ratio for each cinematic video-frame artwork area inside the storyboard."
+        },
+        "targetVideoAspectRatio": {
+          "type": "string",
+          "description": "Final video aspect ratio, such as 9:16 for vertical social video."
+        },
+        "boardDimensions": {
+          "type": "string",
+          "description": "Optional exact storyboard board dimensions, such as 2560x1440 or 1440x2560."
+        }
+      }
+    },
+    "scenes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "index", "visibleText", "metadataLabels", "referenceUsage"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "index": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 24
+          },
+          "visibleText": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Only text that should actually appear inside the final video frame, such as brand copy, CTA text, signage, captions, or diegetic text."
+          },
+          "metadataLabels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Production labels, timing notes, scene numbers, overlay markers, placeholders, and other notes that may guide the storyboard but must not be rendered inside a video scene or Seedance output."
+          },
+          "referenceUsage": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "endCard": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["visibleText", "metadataLabels"],
+      "properties": {
+        "visibleText": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "metadataLabels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "metadataLabels": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/dist-esm/schemas/tools/add_subtitles.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/add_subtitles.schema.json",
+  "title": "add_subtitles arguments",
+  "schemaVersion": "2026-04-27.1",
+  "description": "Burn subtitles into a video from caller-supplied cues or an SRT/VTT string. Use when the user asks to add captions, subtitles, on-screen dialogue, or burned-in lyrics to a video. Either pass `cues` as an array of {startSeconds, endSeconds, text}, or pass a full `srt` string. Pace cues like real subtitles: split the script into multiple short cues (typically 1.5–4 seconds each, ~1–8 words per cue, roughly 15–20 characters per second of cue duration). Never burn a single cue that spans the entire clip — even a static image should get progressively revealed lines, not one paragraph held on screen the whole time. Auto-transcription (auto_transcribe=true) is not yet enabled and will return USER_INPUT_INCOMPLETE — when the user has not supplied lines, ask them for the cue text and timing instead of calling with auto_transcribe. If the user explicitly asks you to write, invent, improvise, or make up captions/subtitles, create a few short, generic cue lines yourself and call this tool with cues; do not ask a follow-up for exact wording in that case.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "sourceVideoIndex": {
+      "type": "number",
+      "description": "Which video to subtitle. Default: -1 (most recent generated or uploaded video). Non-negative values are 0-based indices into prior generated video results. Negative values reference uploaded videos."
+    },
+    "cues": {
+      "type": "array",
+      "description": "Ordered subtitle cues. Each cue has startSeconds, endSeconds, and the line of text to display. Provide either `cues` or `srt`, not both. Aim for multiple short cues (1.5–4s each, ~1–8 words) rather than one long cue spanning the full clip.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "startSeconds": {
+            "type": "number",
+            "minimum": 0
+          },
+          "endSeconds": {
+            "type": "number",
+            "minimum": 0
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "startSeconds",
+          "endSeconds",
+          "text"
+        ]
+      }
+    },
+    "srt": {
+      "type": "string",
+      "description": "Full SRT (or VTT) document as a string, used in place of `cues`. Useful when the user pastes a subtitle file directly. Provide either `cues` or `srt`, not both."
+    },
+    "auto_transcribe": {
+      "type": "boolean",
+      "description": "Reserved for future speech-to-text support. Currently returns USER_INPUT_INCOMPLETE so the LLM can ask the user to supply cues. Do not set this — gather cue text from the user instead."
+    },
+    "style": {
+      "type": "object",
+      "description": "Optional styling overrides for the burned subtitles.",
+      "properties": {
+        "fontSizePct": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 30,
+          "description": "Font size as a percentage of the video height. Default 6."
+        },
+        "color": {
+          "type": "string",
+          "description": "Subtitle fill color. Default \"#FFFFFF\"."
+        },
+        "outlineColor": {
+          "type": "string",
+          "description": "Subtitle outline color. Default \"#000000\"."
+        },
+        "position": {
+          "type": "string",
+          "enum": [
+            "bottom",
+            "top",
+            "center"
+          ],
+          "description": "Vertical placement of the subtitle line. Default \"bottom\"."
+        }
+      }
+    }
+  }
+}

package/dist-esm/schemas/tools/animate_photo.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/animate_photo.schema.json",
+  "title": "animate_photo arguments",
+  "schemaVersion": "2026-04-27.1",
+  "description": "Animate a photo into video with motion, audio, and dialogue using LTX 2.3 or WAN 2.2. Do NOT use this tool for seedance2 or seedance2-fast. Seedance 2.0 media references must go through generate_video with referenceImageIndices/referenceVideoIndices/referenceAudioIndices and @Image/@Video/@Audio role text in the prompt; for seamless-loop Seedance requests with one uploaded image, the prompt should anchor it as both the first frame and last frame. LTX/WAN NOTE: uploaded audio files are not loose references for ltx23/wan22; use sound_to_video when uploaded audio is the primary sync target. DANCE REQUESTS (\"make them dance\", \"do the X dance\"): use dance_montage — NOT this tool. LTX 2.3 generates audio natively — describe dialogue and ambient sounds directly in the prompt (do NOT pre-generate audio for this tool). If the user provides exact speech, include it in double quotes; if they only imply speech, describe the performance and voice without inventing quoted words. Never use placeholders such as \"while speaking\", \"dialogue begins\", \"explaining\", or \"final line lands\". PERSONA VOICE: Only when the user explicitly asks to use/clone a registered persona voice clip, call resolve_personas first, then set voicePersonaName to select which persona's voice clip to use. Do not set voicePersonaName for ordinary character dialogue or inferred voices; describe those voices in the prompt for native LTX audio. For cross-persona narration (e.g. David narrates a video of Aleyna), resolve both personas and set voicePersonaName to the narrator only if that registered voice was requested. Persona voice requires ltx23 — always use ltx23 when persona voice is requested (WAN 2.2 does not support voice identity). PERSONA PIPELINE: For persona videos, ensure an image of the persona exists before calling animate_photo. The standard pipeline is: resolve_personas → edit_image → animate_photo. If a suitable persona image already exists (user uploaded one, a prior edit_image/generate_image result, OR the user explicitly says to use the Persona image/reference photo directly), skip edit_image and animate directly. After resolve_personas, this tool can animate the injected persona image directly when that explicit direct-use instruction is given. Auto-uses the latest result image (from any prior tool) unless sourceImageIndex is set. Supports start-frame (default), end-frame, and start+end interpolation modes for LTX/WAN — ask the user which frame role their image should play if they mention \"end frame\", \"last frame\", or provide two images. FIRST+LAST FRAME WORKFLOW: When the user wants a non-Seedance video using two different scenes as start and end frames, FIRST generate both images in a single generate_image/edit_image call with numberOfVariations=2 and Dynamic Prompts, THEN call animate_photo with frameRole=\"both\", sourceImageIndex=0, endImageIndex=1. Never generate the two frames in separate tool calls. In frameRole=\"both\", the handler automatically inspects both images and upgrades the base prompt into a scene-aware smooth transition prompt, so your prompt should state the desired transition style, action, dialogue, and audio rather than trying to list every visible object. If the request is vague, analyze the image first and suggest 2-3 specific animation ideas tailored to what you see. Only call once you have clear creative intent. N-VIDEOS PATTERN — ALWAYS BATCH IN ONE CALL: When the user wants N video versions or a multi-segment stitched non-Seedance video, NEVER call animate_photo N times. Always use sourceImageIndices in a single call so all N projects run in parallel. sourceImageIndices supports up to 16 entries; there is NO 3-clip cap, so do not split one planned batch into \"first 3\" and \"remaining\" calls. For a dialogue-heavy total-duration request with no explicit per-clip duration, prefer 15-second clips (30s total = 2 clips × 15s), not 5×6s or 6×5s. Two flavors: (A) SHARED CONTENT — when all N clips have the same dialogue/motion but different source visuals (different scenes, outfits, environments, persona looks), first generate N distinct images via ONE edit_image/generate_image call with numberOfVariations=N + Dynamic Prompts {|}, then call animate_photo with sourceImageIndices=[start..start+N-1] and a single shared `prompt`. If all segments intentionally reuse the primary uploaded image instead of generated source images, use sourceImageIndices=[-1,-1,...] with one -1 per segment. For a long or multi-segment video from a single supplied/uploaded image WITHOUT a requested image/keyframe/version generation stage, use sourceImageIndices=[-1,-1,...] and per-clip prompts. Only set frameRole=\"both\" and endImageIndex=-1 when the user explicitly says the same uploaded/source/original image should be both the first and last frame of every segment. If the user requests generated source images first, honor that image stage, then animate the generated result indices. When using generated scene keyframes and each clip should begin and end on its own scene image for stitching, call animate_photo with frameRole=\"both\" and sourceImageIndices=[start..end] but OMIT endImageIndex; do not set endImageIndex=-1 unless every source is the uploaded image. (B) PER-CLIP CONTENT — when each clip has DIFFERENT dialogue, jokes, narration, or motion (e.g. \"4 videos where each tells a different joke\"), pass BOTH sourceImageIndices AND `prompts` (an array of N strings, one per clip) in the same single call. Each prompt must independently anchor the visible characters, scene action, camera, audio, exact screenplay-style speaker tags, and exact quoted dialogue for that segment. If you just wrote or displayed a script/table, copy the exact dialogue lines into the corresponding per-clip prompts; do not summarize them as speech activity. If using named speaker tags with any multi-person reference image or generated scene keyframe, include one explicit cast map in each prompt that binds each name to visible position, clothing, and props/actions, e.g. SPEAKER_A = left person holding a prop; SPEAKER_B = center person with tablet; SPEAKER_C = right person near table. Do not also describe the same people again as generic man/boy/girl/woman/character subjects. For screenplay, storyboard, commercial, series, or other longer-form tasks with recurring characters, preserve the same character names and repeated visual anchors in every per-clip prompt where each character appears. The fan-out launches all N projects in parallel with their respective per-clip prompts. Use the standard single-source path (numberOfVariations only) when the user wants motion variety from a single fixed frame instead.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "I2V RULE: Do NOT re-describe what is visible in the input image. Focus on the transition from stillness — motion, expression changes, what happens next, camera movement, and sound.\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing. Set skipPromptProcessing=true; for Seedance also set expandPrompt=false.\n\nSTRUCTURE: \"[How the subject begins to move]. [What changes next]. [Camera behavior]. [Audio].\"\n\nMOTION PACING: Scale complexity to duration. <=6s: 1 main action beat + 1 simple camera move. Around 10s: 2-3 clear action beats + 1 camera move. >10s: up to 4 action beats in clear sequence. Prefer fewer readable beats over dense micro-actions, especially in short clips.\n\nBLOCKING: Use the image as the anchor and direct only meaningful layout changes. If the prompt introduces multiple moving subjects, state left/right placement, foreground/background, facing toward/away, and relative distance.\n\nACTION: One flowing paragraph. Describe motion beat by beat with temporal connectors (\"as\", \"then\", \"while\"). Specify who moves, what moves, how it moves, and what the camera does. One main thread — avoid too many actions at once or generic phrases like \"comes alive.\"\n\nDIALOGUE: Put user-provided spoken lines in double quotes. For screenplay-style or longer-form tasks, prefix each spoken line with a stable speaker tag outside the quotes, e.g. CHARACTER: \"We made it.\" Break long speech into short quoted phrases with acting beats between them (gestures, pauses, glances). If the user asks for speech but provides no exact words, describe the visible delivery, voice quality, and emotion without inventing quoted dialogue; ask only when exact wording is the point of the request. Never write placeholders such as \"while speaking\", \"dialogue begins\", \"explaining\", or \"final line lands\". Show emotion through visible behavior, not labels. LTX 2.3 generates audio natively. QUOTING RULE: ONLY use double quotes for spoken dialogue. Never quote on-screen text, overlay text, titles, captions, signs, or any visual text — describe them without quotes (e.g. bold white text reading CONGRATULATIONS overlays the lower third).\n\nAUDIO: Prompt sound intentionally — voice quality, volume, room tone, ambience, music, weather, footsteps. Include language or accent if relevant. Useful voice/volume anchors: whisper, mutter, shout, scream, energetic announcer, resonant voice with gravitas, distorted radio-style, robotic monotone, childlike curiosity.\n\nCAMERA: Cinematic terms — slow push-in, static tripod, handheld, slow arc, dolly in. Describe movement relative to subject.\n\nFor first+last-frame transitions (frameRole=\"both\"), write a concise base request for the transition style, action, dialogue, and audio. The handler will inspect both frames and expand it into a scene-aware prompt that maps visible objects and subjects between frames.\n\nFor specific characters (movies, TV): describe visual appearance — don't rely on names alone.\n\nFor complex/creative scenes (characters talking, skits), capture full creative intent — system auto-expands into detailed prompt.\n\nAVOID: Re-describing the image, vague prompts, too many actions at once, abstract emotions without visible behavior, rigid numeric constraints, readable text or logos.\n\nWAN 2.2 (\"wan22\"): 30-150 words, subtle natural movements.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary motion, camera, or atmosphere while preserving the user's specified elements. Example: \"{gentle sway with soft birdsong|dramatic zoom with rolling thunder|slow pan with ambient music}\"."
+    },
+    "expandPrompt": {
+      "type": "boolean",
+      "description": "Optional. Set false only for pipeline-authored prompts that should bypass model-specific prompt expansion."
+    },
+    "skipPromptProcessing": {
+      "type": "boolean",
+      "description": "Bypass automatic prompt shaping/refinement, image-description anchoring, transition-prompt rewriting, and voice-identity prompt formatting so the prompt text is sent unchanged to the video model. Set true ONLY when the user explicitly says not to modify/rewrite/enhance/expand/change/improve the prompt, or to use/send it exactly, verbatim, or as-is, AND the provided prompt already satisfies the tool requirements. Continue to set non-prompt parameters such as source indices, frameRole, model, duration, count, and aspect ratio. For Seedance literal prompt requests, also set expandPrompt=false. Do not set for ordinary underspecified requests."
+    },
+    "videoModel": {
+      "type": "string",
+      "enum": [
+        "ltx23",
+        "wan22"
+      ],
+      "description": "Which video model to use. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Use ltx23 for most requests. Use wan22 for quick simple motions without audio. Default: \"ltx23\". Do not set seedance2 or seedance2-fast here; use generate_video with referenceImageIndices and @Image role text for Seedance."
+    },
+    "negativePrompt": {
+      "type": "string",
+      "description": "Optional negative prompt for LTX/Wan image-to-video models. Use only when the user explicitly states what should be avoided; do not use this field for Seedance workflows."
+    },
+    "duration": {
+      "type": "number",
+      "description": "Video duration in seconds. Default: 5. Use when the user explicitly requests a specific length (e.g., \"make a 10 second video\"). Range: 2-20."
+    },
+    "targetResolution": {
+      "type": "number",
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source image aspect ratio. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+    },
+    "sourceImageIndex": {
+      "type": "number",
+      "description": "Which image to use as the START frame. Use 0-based non-negative indices for generated result images. Use negative indices for uploaded images: -1 = first/primary upload, -2 = second upload, -3 = third upload, etc. Omit to auto-select: uses the latest result for \"start\"/\"end\" modes, or the FIRST result for \"both\" mode. IMPORTANT: When frameRole is \"both\", set this to the start frame image index and endImageIndex to the end frame image index."
+    },
+    "sourceImageIndices": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "minItems": 1,
+      "maxItems": 16,
+      "description": "Array of source frame indices — one video is generated per entry as its own SDK project, all running in PARALLEL. Use 0-based non-negative result indices for generated images. Use negative indices for uploaded images: -1 = first/primary upload, -2 = second upload, -3 = third upload, etc. Repeating -1 is allowed and is REQUIRED for multi-segment videos that reuse the same uploaded image as every segment's start frame. By default all projects share the `prompt`/`voice`/`duration`, but you can pass `prompts` (array) to give each clip its own dialogue/motion. ALWAYS use this for non-Seedance \"N videos\" or multi-segment request — never call animate_photo N times sequentially. Do NOT combine with `numberOfVariations`, `sourceImageIndex`, or frameRole=\"end\". You MAY combine with frameRole=\"both\" when clips need end frames. For adjacent transition chains across generated images, use sourceImageIndices=[start..end-1] and endImageIndices=[start+1..end] so N images produce N-1 transition clips. If the uploaded/original image starts the chain and generated results are the remaining frames, use sourceImageIndices=[-1,start..end-1] and endImageIndices=[start..end]. If the user supplies multiple uploaded images as the actual keyframe sequence, use adjacent negative uploaded indices, e.g. 5 uploaded images become sourceImageIndices=[-1,-2,-3,-4], endImageIndices=[-2,-3,-4,-5], frameRole=\"both\", prompts length 4, then stitch_video. If the user specifies transition motion, camera behavior, actions, dialogue, or audio, copy those instructions into every corresponding per-clip prompt; only invent a generic smooth transition when the user does not specify one. If the user asks for a seamless loop or final transition from the last image back to the first, close the chain by including the last image as a source and the first image as the final end frame, e.g. 5 uploaded images become sourceImageIndices=[-1,-2,-3,-4,-5], endImageIndices=[-2,-3,-4,-5,-1]. For generated scene keyframes that should each loop to themselves, omit endImageIndex/endImageIndices so each source image is also its own end frame. Set endImageIndex=-1 only when every sourceImageIndices entry is also -1 and every segment reuses the first uploaded image. Range: 1–16 indices. For generated image batches, values MUST be read from the latest edit_image/generate_image tool result's `startIndex` field. If startIndex=3 and 4 images were generated in that batch, pass `[3,4,5,6]` (NOT `[0,1,2,3]`). Do NOT assume generated indices start at 0 — they don't if there are prior results in the conversation."
+    },
+    "prompts": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "maxItems": 16,
+      "description": "Per-clip prompts for fan-out — use when the user wants DIFFERENT dialogue, jokes, narration, or motion in each video. MUST be paired with `sourceImageIndices` and have the SAME length. Each entry is the full prompt for the corresponding source image. If a clip has speech, include exact spoken words in double quotes with stable speaker tags; do NOT write placeholders like \"while speaking\", \"dialogue begins\", \"explaining\", or \"final line lands\". If you just wrote a script/table/storyboard, copy that clip's exact dialogue into this prompt. When named speakers appear in a multi-person reference image or generated keyframe, start each entry with one compact cast map that binds names to visible anchors before dialogue, e.g. Cast map: SPEAKER_A is the left person holding the prop; SPEAKER_B is the center person with the tablet; SPEAKER_C is the right person near the table. Then move directly into action/dialogue; do not describe those same people again as generic man/boy/girl/woman/character subjects. This prevents speaker tags from being assigned to the wrong visible character. When set, the top-level `prompt` parameter is ignored (still required by the schema — just pass any descriptive string, e.g. a brief summary of the batch). Example: 4 source images of a couple, \"make each video have a different joke\" → sourceImageIndices=[0,1,2,3], prompts=[\"Cast map: She is the left woman in the blue dress; He is the right man in the gray jacket. She says: \\\"Why did the scarecrow win an award?\\\" He grins.\", \"Cast map: He is the right man in the gray jacket; She is the left woman in the blue dress. He says: \\\"Because he was outstanding in his field!\\\" She laughs.\", \"...\", \"...\"]. Omit this when all clips share the same dialogue/motion (visual variety only) — fan-out will use the shared `prompt` for every clip."
+    },
+    "numberOfVariations": {
+      "type": "number",
+      "description": "Number of variations (1-16). Use 1 unless user explicitly requests multiple separate video outputs.",
+      "minimum": 1,
+      "maximum": 16
+    },
+    "aspectRatio": {
+      "type": "string",
+      "description": "Do NOT set unless the user explicitly requests an aspect ratio, format, orientation, or exact pixel dimensions. When a reference/source image is used and the user did not ask to change its shape, omit this field so the handler preserves the selected source image's own ratio.\n\nFormats: \"16:9\", \"9:16\", \"4:5\", \"1:1\", \"4:3\", \"3:2\", \"21:9\", or exact pixels like \"1920x1080\".\n\nCRITICAL: When the user specifies exact pixel dimensions (e.g., \"1280x720\", \"1080x1920\", \"1920x1080\", \"3840x2160\") or an orientation-qualified named resolution (e.g., \"720p landscape\", \"720p portrait\"), use the exact pixel format, NOT a ratio like \"16:9\" or \"9:16\". Exact user-requested dimensions override the selected default media quality, including Pro/HQ defaults. A bare named video resolution like \"720p resolution\" is only a resolution tier/short-side request; do not turn it into landscape pixels and do not set aspectRatio unless the user also states landscape, portrait, vertical, horizontal, or exact pixels. If requested pixels are in bounds but not on the model's pixel step, still pass the user's exact pixel request; the handler snaps to the nearest supported size internally. Only use ratio format when the user says a generic format name without pixel dimensions.\n\nMappings (use ONLY when user does NOT specify pixel dimensions): landscape/widescreen/YouTube/cinematic → \"16:9\". portrait → \"9:16\". TikTok/Reels/IG Reels → \"1080x1920\". ultrawide/cinema scope → \"21:9\". Instagram post → \"4:5\". square → \"1:1\". standard/TV → \"4:3\". 720p landscape → \"1280x720\". 720p portrait → \"720x1280\". 1080p landscape → \"1920x1080\". 1080p portrait/HD portrait → \"1080x1920\". 4K landscape → \"3840x2160\". 4K portrait → \"2160x3840\". Never set for generic requests like \"make a video\"."
+    },
+    "frameRole": {
+      "type": "string",
+      "enum": [
+        "start",
+        "end",
+        "both"
+      ],
+      "description": "How to use the source image(s) for non-Seedance video generation. \"start\" (default): image is the first frame — video animates forward from it. \"end\": image is the last frame — video leads up to it. \"both\": two images provided — interpolates between start and end frames. For single clips using \"both\", set sourceImageIndex to the start frame and endImageIndex to the end frame. For sourceImageIndices fan-out using repeated -1, use frameRole=\"both\" and set endImageIndex=-1 when every segment must use the uploaded image as the shared last frame. For adjacent generated-image transitions, use frameRole=\"both\" with matching sourceImageIndices and endImageIndices arrays. Omit endImageIndex/endImageIndices only when each source image should also be its own end frame. The handler inspects different start/end frames and generates a detailed transition prompt automatically."
+    },
+    "endImageIndex": {
+      "type": "number",
+      "description": "Which image to use as the END frame. Use 0-based non-negative indices for generated results. Use negative indices for uploaded images: -1 = first/primary upload, -2 = second upload, -3 = third upload, etc. For a single frameRole=\"both\" transition between two different images, set this to the desired end frame. For sourceImageIndices fan-out where each generated keyframe should also be its own last frame, OMIT this field. Use a shared uploaded endImageIndex only when every sourceImageIndices entry is also an uploaded image; otherwise use endImageIndices for per-clip end frames."
+    },
+    "endImageIndices": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "minItems": 1,
+      "maxItems": 16,
+      "description": "Per-clip END frame indices for sourceImageIndices fan-out. Use ONLY with frameRole=\"both\". Length MUST exactly match sourceImageIndices. Use 0-based non-negative indices for generated results and negative indices for uploaded images (-1 first upload, -2 second upload, etc.). Use this for transition chains between generated images, e.g. 5 generated images at indices [0,1,2,3,4] should become 4 transition clips with sourceImageIndices=[0,1,2,3], endImageIndices=[1,2,3,4], prompts length 4, duration as requested, then stitch_video. If the chain starts on the uploaded image and continues through generated results [0,1,2,3], use sourceImageIndices=[-1,0,1,2] and endImageIndices=[0,1,2,3]. If the user supplies 5 uploaded images as the sequence, use sourceImageIndices=[-1,-2,-3,-4] and endImageIndices=[-2,-3,-4,-5]. If the user requests a seamless loop or final transition back to the first image, append that loop closure: sourceImageIndices=[-1,-2,-3,-4,-5], endImageIndices=[-2,-3,-4,-5,-1]. Do NOT also set endImageIndex when using this."
+    },
+    "voicePersonaName": {
+      "type": "string",
+      "description": "ONLY when the user explicitly requests a registered/reference persona voice clip. Name of the persona whose voice clip to use as referenceAudioIdentity. Set this when the narrator/speaker is a different persona than the one shown in the video (e.g. \"David\" narrates a video of Aleyna), or to explicitly select a requested voice when multiple personas with voice clips are resolved. Do NOT set this for ordinary character dialogue, inferred voices, or personas without a voice clip — LTX 2.3 generates voice natively from the text prompt instead. Requires ltx23."
+    }
+  },
+  "required": [
+    "prompt"
+  ]
+}

package/dist-esm/schemas/tools/apply_style.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/apply_style.schema.json",
+  "title": "apply_style arguments",
+  "schemaVersion": "2026-04-27.1",
+  "description": "Apply an artistic style, era-specific look, or creative transformation to a photo. Use when the user wants to change the visual style (e.g., \"make it look like the 70s\", \"oil painting style\", \"vintage polaroid look\"). Can handle any creative transformation. One style per call. IMPORTANT: When previous results exist, this tool automatically uses the LATEST result image unless you specify a different sourceImageIndex or the user explicitly says \"original\". So just call it without sourceImageIndex for follow-up requests.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "Style prompt for Qwen Image Edit 2511 (50-200 words, natural language sentences).\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing.\n\nPROMPT ORDER: [IDENTITY LOCK if people] → [STYLE TRANSFER INSTRUCTION] → [PRESERVE UNMENTIONED DETAILS]\n\nRules:\n- Use POSITIVE phrasing only. The model ignores negatives (\"preserve exact facial likeness\" NOT \"don't change the face\").\n- Transfer the visual STYLE ONLY, not the identity. Borrow palette, texture, contrast behavior, and stylistic treatment — NOT face structure.\n- Reference known art styles, artists, and franchises BY NAME to anchor the style — be specific, never generic.\n- Describe specific visual characteristics: brushstrokes, color palette, texture, composition approach, mood.\n- For era looks: describe the photographic qualities of that era (e.g., \"warm faded Kodachrome tones with soft vignette, typical of 1970s amateur photography\").\n- CRITICAL for photos with people: FRONT-LOAD identity preservation BEFORE the style instruction. Start with \"Preserve exact facial likeness, face structure, eye shape, nose shape, mouth shape, jawline, skin tone, hairline, apparent age, and overall recognizability.\" Then describe the style. End with \"Keep the subject recognizable as the same person. Maintain exact positioning, poses, and composition.\"\n- Go bold with pop culture and iconic styles: \"Andy Warhol pop art with bold neon screen-print colors\", \"Banksy stencil street art with gritty urban textures\", \"Studio Ghibli watercolor with soft pastoral warmth\", \"Pixar 3D render with glossy skin and exaggerated features\", \"Tim Burton gothic with pale skin and dark spiraling backgrounds\", \"Van Gogh Starry Night with thick impasto swirls and vibrant blues\", \"Takashi Murakami superflat with psychedelic flowers and bold outlines\".\n- Always end with \"Preserve the subject's identity, pose, and composition.\""
+    },
+    "sourceImageIndex": {
+      "type": "number",
+      "description": "Which result image to apply the style to (0-based index). Omit to use the latest result automatically (or the original if no results exist). Only set explicitly when the user specifies a particular image number or explicitly says \"original\" (use -1 for original)."
+    },
+    "scale": {
+      "type": "number",
+      "enum": [
+        1,
+        1.5,
+        2,
+        3,
+        4
+      ],
+      "description": "Output scale multiplier relative to the source image size. 1 = same resolution as source (default). Use higher values when user asks to upscale, enlarge, make bigger, or increase resolution. Small images (<480px) are automatically upscaled to at least 480px regardless of this setting. Default: 1."
+    },
+    "aspectRatio": {
+      "type": "string",
+      "description": "Do NOT set unless the user explicitly requests an aspect ratio, format, orientation, or exact pixel dimensions. When a reference/source image is used and the user did not ask to change its shape, omit this field so the handler preserves the selected source image's own ratio.\n\nFormats: \"16:9\", \"9:16\", \"4:5\", \"1:1\", \"4:3\", \"3:2\", \"21:9\", or exact pixels like \"1920x1080\".\n\nCRITICAL: When the user specifies exact pixel dimensions (e.g., \"1280x720\", \"1080x1920\", \"1920x1080\", \"3840x2160\") or an orientation-qualified named resolution (e.g., \"720p landscape\", \"720p portrait\"), use the exact pixel format, NOT a ratio like \"16:9\" or \"9:16\". Exact user-requested dimensions override the selected default media quality, including Pro/HQ defaults. A bare named video resolution like \"720p resolution\" is only a resolution tier/short-side request; do not turn it into landscape pixels and do not set aspectRatio unless the user also states landscape, portrait, vertical, horizontal, or exact pixels. If requested pixels are in bounds but not on the model's pixel step, still pass the user's exact pixel request; the handler snaps to the nearest supported size internally. Only use ratio format when the user says a generic format name without pixel dimensions.\n\nMappings (use ONLY when user does NOT specify pixel dimensions): landscape/widescreen/YouTube/cinematic → \"16:9\". portrait → \"9:16\". TikTok/Reels/IG Reels → \"1080x1920\". ultrawide/cinema scope → \"21:9\". Instagram post → \"4:5\". square → \"1:1\". standard/TV → \"4:3\". 720p landscape → \"1280x720\". 720p portrait → \"720x1280\". 1080p landscape → \"1920x1080\". 1080p portrait/HD portrait → \"1080x1920\". 4K landscape → \"3840x2160\". 4K portrait → \"2160x3840\". Never set for generic requests like \"make a video\"."
+    }
+  },
+  "required": [
+    "prompt"
+  ]
+}

package/dist-esm/schemas/tools/change_angle.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/change_angle.schema.json",
+  "title": "change_angle arguments",
+  "schemaVersion": "2026-04-27.1",
+  "description": "Generate the photo from a different camera angle or perspective. Uses AI to create a new view of the subject as if photographed from a different position. Use when the user wants to see the subject from another angle, generate a different view, create a portrait from a specific direction, or get a closeup/wide shot. Examples: \"show me from the left side\", \"generate a 3/4 portrait view\", \"closeup from slightly above\". IMPORTANT: When previous results exist, this tool automatically uses the LATEST result image unless you specify a different sourceImageIndex or the user explicitly says \"original\".",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "EXACT camera angle string. You MUST construct this by concatenating exactly one value from each category below, separated by single spaces. No commas, no extra words.\n\nFormat: \"[azimuth] [elevation] [distance]\"\n\nAzimuth (pick one): \"front view\", \"front-right quarter view\", \"right side view\", \"back-right quarter view\", \"back view\", \"back-left quarter view\", \"left side view\", \"front-left quarter view\"\nElevation (pick one): \"low-angle shot\", \"eye-level shot\", \"elevated shot\", \"high-angle shot\"\nDistance (pick one): \"close-up\", \"medium shot\", \"wide shot\"\n\nExamples:\n- \"front-right quarter view eye-level shot medium shot\"\n- \"left side view eye-level shot close-up\"\n- \"front view low-angle shot wide shot\"\n- \"right side view elevated shot medium shot\"\n\nMap user requests: \"from the left\" → \"left side view\", \"looking up at\" → \"low-angle shot\", \"closeup\" → \"close-up\", \"3/4 view\" → \"front-right quarter view\" or \"front-left quarter view\", \"portrait\" → \"front-right quarter view eye-level shot medium shot\".\nDefault elevation to \"eye-level shot\" and distance to \"medium shot\" when not specified."
+    },
+    "sourceImageIndex": {
+      "type": "number",
+      "description": "Which result image to use as source (0-based index). Omit to use the latest result automatically (or the original if no results exist). Only set explicitly when the user specifies a particular image number or explicitly says \"original\" (use -1 for original)."
+    },
+    "loraStrength": {
+      "type": "number",
+      "description": "LoRA strength for angle generation (0.1-1.0). Default: 0.9. Lower values preserve more of the original appearance, higher values produce stronger angle changes. Only set when the user wants to control the transformation intensity."
+    },
+    "aspectRatio": {
+      "type": "string",
+      "description": "Do NOT set unless the user explicitly requests an aspect ratio, format, orientation, or exact pixel dimensions. When a reference/source image is used and the user did not ask to change its shape, omit this field so the handler preserves the selected source image's own ratio.\n\nFormats: \"16:9\", \"9:16\", \"4:5\", \"1:1\", \"4:3\", \"3:2\", \"21:9\", or exact pixels like \"1920x1080\".\n\nCRITICAL: When the user specifies exact pixel dimensions (e.g., \"1280x720\", \"1080x1920\", \"1920x1080\", \"3840x2160\") or an orientation-qualified named resolution (e.g., \"720p landscape\", \"720p portrait\"), use the exact pixel format, NOT a ratio like \"16:9\" or \"9:16\". Exact user-requested dimensions override the selected default media quality, including Pro/HQ defaults. A bare named video resolution like \"720p resolution\" is only a resolution tier/short-side request; do not turn it into landscape pixels and do not set aspectRatio unless the user also states landscape, portrait, vertical, horizontal, or exact pixels. If requested pixels are in bounds but not on the model's pixel step, still pass the user's exact pixel request; the handler snaps to the nearest supported size internally. Only use ratio format when the user says a generic format name without pixel dimensions.\n\nMappings (use ONLY when user does NOT specify pixel dimensions): landscape/widescreen/YouTube/cinematic → \"16:9\". portrait → \"9:16\". TikTok/Reels/IG Reels → \"1080x1920\". ultrawide/cinema scope → \"21:9\". Instagram post → \"4:5\". square → \"1:1\". standard/TV → \"4:3\". 720p landscape → \"1280x720\". 720p portrait → \"720x1280\". 1080p landscape → \"1920x1080\". 1080p portrait/HD portrait → \"1080x1920\". 4K landscape → \"3840x2160\". 4K portrait → \"2160x3840\". Never set for generic requests like \"make a video\"."
+    }
+  },
+  "required": [
+    "description"
+  ]
+}

package/dist-esm/schemas/tools/compose_instrumental.schema.json

@@ -0,0 +1,24 @@
+{
+  "title": "compose_instrumental tool schema",
+  "schemaVersion": "2026-05-14.1",
+  "description": "Synchronous instrumental music structure composition utility.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["prompt"],
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "The instrumental music topic, mood, genre, scene, campaign, or composition request."
+    },
+    "music_prompt": {
+      "type": "string",
+      "description": "Optional musical style context, instrumentation, mood, or production direction."
+    },
+    "duration_seconds": {
+      "type": "number",
+      "minimum": 10,
+      "maximum": 600,
+      "description": "Optional desired track duration in seconds."
+    }
+  }
+}

package/dist-esm/schemas/tools/compose_lyrics.schema.json

@@ -0,0 +1,28 @@
+{
+  "title": "compose_lyrics tool schema",
+  "schemaVersion": "2026-05-14.1",
+  "description": "Synchronous song lyric composition utility for vocal music.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["prompt"],
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "The song topic, mood, genre, scene, campaign, or lyric request."
+    },
+    "language": {
+      "type": "string",
+      "description": "Optional language code or language name for the lyrics."
+    },
+    "music_prompt": {
+      "type": "string",
+      "description": "Optional musical style context, genre, instrumentation, mood, or production direction."
+    },
+    "duration_seconds": {
+      "type": "number",
+      "minimum": 10,
+      "maximum": 600,
+      "description": "Optional desired song duration in seconds."
+    }
+  }
+}

package/dist-esm/schemas/tools/compose_script.schema.json

@@ -0,0 +1,68 @@
+{
+  "title": "compose_script tool schema",
+  "schemaVersion": "2026-05-14.1",
+  "description": "Synchronous creative writing utility for scripts, storyboards, video prompts, ad concepts, trailers, social shorts, campaign beats, and talking-head plans.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["brief"],
+  "properties": {
+    "brief": {
+      "type": "string",
+      "description": "The creative writing brief, story idea, product concept, video idea, or revision request."
+    },
+    "script_type": {
+      "type": "string",
+      "enum": ["video_prompt", "screenplay", "storyboard", "ad_script", "trailer", "social_short", "talking_head", "campaign", "revision"],
+      "description": "The kind of script or creative writing artifact to produce."
+    },
+    "destination_model": {
+      "type": "string",
+      "description": "Optional destination video model selector, such as ltx23, wan22, or seedance2."
+    },
+    "destination_tool": {
+      "type": "string",
+      "description": "Optional downstream tool, such as generate_video, animate_photo, sound_to_video, or video_to_video."
+    },
+    "duration_seconds": {
+      "type": "number",
+      "minimum": 1,
+      "maximum": 300,
+      "description": "Requested runtime for a video prompt, social short, ad, or talking-head script."
+    },
+    "scene_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 12,
+      "description": "Requested number of scenes, shots, beats, or storyboard panels."
+    },
+    "aspect_ratio": {
+      "type": "string",
+      "description": "Optional target aspect ratio, such as 16:9, 9:16, 1:1, 4:5, or 21:9."
+    },
+    "platform": {
+      "type": "string",
+      "description": "Optional target platform or context, such as TikTok, YouTube Shorts, Instagram Reels, broadcast, landing page, game trailer, or pitch deck."
+    },
+    "style": {
+      "type": "string",
+      "description": "Optional style, genre, tone, visual treatment, or brand voice to preserve."
+    },
+    "first_frame_description": {
+      "type": "string",
+      "description": "Optional description of the starting frame when composing an image-to-video prompt without attached vision content."
+    },
+    "first_frame_data_url": {
+      "type": "string",
+      "description": "Optional inline image data URI for the starting frame when composing an image-to-video or first-frame video prompt."
+    },
+    "last_frame_data_url": {
+      "type": "string",
+      "description": "Optional inline image data URI for the ending frame when composing an image-to-video transition prompt."
+    },
+    "return_format": {
+      "type": "string",
+      "enum": ["script", "markdown", "json"],
+      "description": "Requested output format. Use script unless structured planning output is explicitly needed."
+    }
+  }
+}

package/dist-esm/schemas/tools/compose_workflow.schema.json

@@ -0,0 +1,67 @@
+{
+  "title": "compose_workflow tool schema",
+  "schemaVersion": "2026-05-14.1",
+  "description": "Synchronous planner that emits a validated durable creative workflow plan from a brief.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["brief"],
+  "properties": {
+    "brief": {
+      "type": "string",
+      "description": "Creative brief describing what the workflow should produce. Free-form natural language. Required."
+    },
+    "scene_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 12,
+      "description": "Suggested number of distinct shots/scenes. The planner may produce more steps than scenes (e.g., keyframe + clip per scene)."
+    },
+    "duration_seconds": {
+      "type": "number",
+      "minimum": 1,
+      "maximum": 120,
+      "description": "Target total duration in seconds for video-bearing plans."
+    },
+    "aspect_ratio": {
+      "type": "string",
+      "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9"],
+      "description": "Output aspect ratio."
+    },
+    "style": {
+      "type": "string",
+      "description": "Optional stylistic guidance (e.g., 'cinematic, neon, low-key', 'whiteboard illustration')."
+    },
+    "destination_models": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "image": {
+          "type": "string",
+          "description": "Preferred image model (e.g., 'flux2', 'gpt-image-2')."
+        },
+        "video": {
+          "type": "string",
+          "description": "Preferred video model (e.g., 'ltx23', 'wan22', 'seedance2')."
+        },
+        "music": {
+          "type": "string",
+          "description": "Preferred music model."
+        }
+      }
+    },
+    "max_estimated_capacity_units": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "If set, the planner attempts to keep total estimated cost at or below this value and returns `fits_budget: false` if it cannot."
+    },
+    "include_audio": {
+      "type": "boolean",
+      "description": "If true, include a music generation step. Defaults to false."
+    },
+    "return_format": {
+      "type": "string",
+      "enum": ["json"],
+      "description": "Currently `json` is the only supported value. Reserved for future."
+    }
+  }
+}