@sogni-ai/sogni-protocol 1.0.0-alpha.2 → 1.0.0-alpha.21

package/schemas/tools/generate_video.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/generate_video.schema.json",
   "title": "generate_video arguments",
   "schemaVersion": "2026-04-27.1",
-  "description": "Generate a video from text or Seedance multimodal references. LTX 2.3 generates audio natively (dialogue, sounds, ambient music) — describe audio in the prompt. 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 (WAN 2.2 does not support voice identity). For non-Seedance syncing to a specific song or audio track, use sound_to_video instead. For non-Seedance animation from a locked source photo, use animate_photo. Do NOT use for My Personas unless generating a Seedance reference-based video — standard persona videos use resolve_personas → edit_image → animate_photo. SEEDANCE DEFAULT: For seedance2 or seedance2-fast, default to exactly one 4-15s video unless the user explicitly asks for multiple separate outputs. Multiple beats, shots, or scene descriptions in one up-to-15s Seedance prompt are still one video. If the user requests one continuous Seedance video longer than 15s, preserve the requested total duration in the prompt/context; chat orchestration should split it into supported segment renders and stitch them instead of clamping it to a 15s excerpt. Uploaded/generated storyboard, shot-sheet, or trailer-concept images used as Seedance references should become one Seedance generate_video call by default; do not extract panels with edit_image and do not animate the storyboard sheet with LTX unless the user explicitly asks for separate non-Seedance clips. Seedance loose image, video, and audio references go through this tool; do not use animate_photo sourceImageIndex/frameRole/endImageIndex for Seedance. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices. If the uploaded audio is the primary sync target, lip-sync target, or requested as sound-to-video/audio-sync, use sound_to_video with videoModel=\"seedance2\" instead of this tool. Use referenceAudioIndices here only when audio is a loose reference under an image/video-anchored Seedance shot. For Seedance, every image — first frame, last frame, or loose reference — is passed through referenceImageIndices (auto-uploaded as referenceImageUrls). Anchor frame intent in the prompt with @Image tags such as \"Use @Image1 as the opening shot reference. Begin the video with a composition, subject placement, lighting, mood, and camera framing that closely match @Image1.\" (or @Image2 as the final shot reference). For seamless-loop or \"first frame and last frame identical\" requests with a single uploaded image, anchor it explicitly as both: \"Use @Image1 as both the first frame and last frame so the video loops cleanly back to the opening composition.\" Assign each useful @Image/@Video/@Audio tag a role. APPROVED STORYBOARD PRODUCTION: When the user asks for a production workflow from an approved storyboard, the chat orchestrator should use the durable CampaignStoryboard contract: render the composite board, audit it, generate per-scene GPT Image 2 keyframes, then render Seedance scene clips and stitch them. Do not replace that with a generic storyboard-reference video unless the user asks for a fast draft. PARTIAL VIDEO EDITS: Do NOT call generate_video to re-render an existing rendered/uploaded video just to change part of it (the bumper, the intro, the end card, a single scene, the last few seconds, etc.). Use replace_video_segment for that — it preserves the unchanged portion, keeps the original audio outside the replaced window, and costs far less. Likewise use extend_video to add new time to the end without rewriting the rest. If the request is vague, ask about vision/mood/style first. Only call once you have clear creative intent.",
+  "description": "Generate a video from text or Seedance multimodal references. LTX 2.5 is the default and generates audio natively; LTX 2.3 remains available as a rollback model and also generates audio natively (dialogue, sounds, ambient music) — describe audio in the prompt. 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 because LTX 2.5 has no compatible ID-LoRA and WAN 2.2 does not support voice identity. For non-Seedance syncing to a specific song or audio track, use sound_to_video instead. For non-Seedance animation from a locked source photo, use animate_photo. Do NOT use for My Personas unless generating a Seedance reference-based video — standard persona videos use resolve_personas → edit_image → animate_photo. SEEDANCE DEFAULT: For seedance2, seedance2-mini, seedance2-fast, or seedance2-5, default to exactly one video (4-15s on 2.0/Mini/Fast, 4-30s on seedance2-5) unless the user explicitly asks for multiple separate outputs. Multiple beats, shots, or scene descriptions in one Seedance prompt within the selected model's per-clip limit are still one video. If the user requests one continuous Seedance video longer than 15s, prefer \"seedance2-5\", which renders up to 30s in a single call; beyond 30s (or on 2.0/Mini/Fast) preserve the requested total duration in the prompt/context and let chat orchestration split it into supported segment renders and stitch them instead of clamping it to a short excerpt. Uploaded/generated storyboard, shot-sheet, or trailer-concept images used as Seedance references should become one Seedance generate_video call by default; do not extract panels with edit_image and do not animate the storyboard sheet with LTX unless the user explicitly asks for separate non-Seedance clips. Seedance loose image, video, and audio references go through this tool; do not use animate_photo sourceImageIndex/frameRole/endImageIndex for Seedance. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices. If the uploaded audio is the primary sync target, lip-sync target, or requested as sound-to-video/audio-sync, use sound_to_video with videoModel=\"seedance2-mini\" instead of this tool unless the user asks for full Seedance. Use referenceAudioIndices here only when audio is a loose reference under an image/video-anchored Seedance shot. For Seedance, every image — first frame, last frame, or loose reference — is passed through referenceImageIndices (auto-uploaded as referenceImageUrls). Anchor frame intent in the prompt with @Image tags such as \"Use @Image1 as the opening shot reference. Begin the video with a composition, subject placement, lighting, mood, and camera framing that closely match @Image1.\" (or @Image2 as the final shot reference). For seamless-loop or \"first frame and last frame identical\" requests with a single uploaded image, anchor it explicitly as both: \"Use @Image1 as both the first frame and last frame so the video loops cleanly back to the opening composition.\" Assign each useful @Image/@Video/@Audio tag a role. APPROVED STORYBOARD PRODUCTION: When the user asks for a production workflow from an approved storyboard, the chat orchestrator should use the durable CampaignStoryboard contract: render the composite board, audit it, generate per-scene GPT Image 2 keyframes, then render Seedance scene clips and stitch them. Do not replace that with a generic storyboard-reference video unless the user asks for a fast draft. PARTIAL VIDEO EDITS: Do NOT call generate_video to re-render an existing rendered/uploaded video just to change part of it (the bumper, the intro, the end card, a single scene, the last few seconds, etc.). Use replace_video_segment for that — it preserves the unchanged portion, keeps the original audio outside the replaced window, and costs far less. Likewise use extend_video to add new time to the end without rewriting the rest. If the request is vague, ask about vision/mood/style first. Only call once you have clear creative intent.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -21,60 +21,70 @@
     },
     "duration": {
       "type": "number",
-      "description": "Video duration in seconds. Default: 5. Range: 2-20. Use when the user explicitly requests a specific length.",
+      "description": "Video duration in seconds. Default: 5. Range: 2-30; the usable window is per-model and the host clamps to it. LTX 2.5, LTX 2.3, and WAN accept 2-20, Seedance 2.0/Mini/Fast accept 4-15, and Seedance 2.5 accepts 4-30 — only \"seedance2-5\" can use the 16-30s part of this range. MiniMax H3 is quantized to a 17-frame grid at a fixed 24 fps and renders 124-362 frames, so an H3 clip runs 5.17-15.08 seconds and a requested length outside that window snaps to the nearest valid H3 length. Use when the user explicitly requests a specific length.",
       "minimum": 2,
-      "maximum": 20
+      "maximum": 30
     },
     "negativePrompt": {
       "type": "string",
-      "description": "Non-Seedance only. Optional negative prompt for video models that expose a separate negative-prompt field. Do not set for seedance2 or seedance2-fast; rewrite user-provided Seedance avoid/ban/no-X requests as positive visual instructions in prompt."
+      "description": "Advanced LTX 2.5/LTX 2.3/WAN only. All standard LTX 2.5 workflow IDs accept this separate negative prompt. Use this field only when the user explicitly asks to set one. MiniMax H3 has no negative-prompt input; put requested exclusions in prompt. Do not set for MiniMax H3, Seedance, or HappyHorse."
     },
     "videoModel": {
       "type": "string",
       "enum": [
+        "ltx25",
         "ltx23",
         "wan22",
         "seedance2",
-        "seedance2-fast"
+        "seedance2-mini",
+        "seedance2-fast",
+        "seedance2-5",
+        "minimax-h3-t2v",
+        "minimax-h3-t2v-turbo",
+        "happyhorse-1.1-t2v",
+        "happyhorse-1.1-i2v",
+        "happyhorse-1.1-r2v",
+        "minimax-h3-r2v",
+        "minimax-h3-r2v-turbo"
       ],
-      "description": "Video model. \"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. Default: \"ltx23\". For ordinary Seedance 2.0 video requests, use seedance2-fast by default: 720p unless Default Media Quality is Fast, which should use 480p. Use seedance2 when the user explicitly asks for 1080p / the non-standard full-quality version, or whenever a generated/uploaded video storyboard image is the Seedance reference unless the user explicitly asks for a draft or the Seedance fast model/version. Storyboard-reference Seedance requests default to High Quality: set targetResolution 720 even when Default Media Quality is Fast, unless the user explicitly asks for another named resolution such as 480p. Default Media Quality Pro alone is not an explicit 1080p request; keep default Seedance resolution at 720p unless the user asks for 1080p or another resolution. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
+      "description": "Video model. \"ltx25\" (default): LTX 2.5 with native audio; Fast/HQ use the official distilled INT8 workflow and Pro uses dev INT8 with the required official distilled Speed LoRA in stage 2. \"ltx23\": LTX 2.3 rollback with its existing distilled/dev quality routing. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx25\". HappyHorse 1.1 can be used here for \"happyhorse-1.1-t2v\" text-to-video, \"happyhorse-1.1-i2v\" with one uploaded/generated first-frame image via referenceImageIndices, or \"happyhorse-1.1-r2v\" with 1-9 image references. For a locked still image/source-frame animation, animate_photo with videoModel=\"happyhorse-1.1-i2v\" is also valid. HappyHorse supports 720p/1080p, 3-15s clips, native synchronized audio that is always on, image-only references, and no negativePrompt or generateAudio input. MiniMax H3 standard text-to-video uses \"minimax-h3-t2v\"; use \"minimax-h3-t2v-turbo\" for the 4-step Turbo tier. The Turbo image-to-video and first-to-last-frame selectors are \"minimax-h3-i2v-turbo\" and \"minimax-h3-flf2v-turbo\"; they keep H3's standard geometry, frame grid, and native-audio contract. MiniMax H3 Ref2VA Turbo uses \"minimax-h3-r2v-turbo\", the dedicated four-step Euler/simple R2V tier with a 960x544 upstream-aligned default. H3 renders 5.17-15.08s clips at a fixed 24 fps inside a 1344x768 pixel budget on a 32px grid, jointly generates its own stereo audio, takes no negativePrompt input, and supports generateAudio=false to return a video without an audio track. MiniMax H3 reference-to-video uses \"minimax-h3-r2v\" for standard quality or \"minimax-h3-r2v-turbo\" for the dedicated four-step Turbo LoRA, a separate ref2va checkpoint and the only H3 mode that takes loose references: up to 9 reference images, 3 reference videos (24 fps, 2-15s, each with an optional soundtrack) and 3 standalone audio tracks, no more than 12 reference files in total, passed with referenceImageIndices/referenceVideoIndices/referenceAudioIndices. At least one visual reference is required: one or more images and/or videos. A video can be the only visual input; audio cannot be the sole input. H3 r2v references are NOT locked frames — name them in the prompt with H3's own 1-based per-type labels <Picture 1>/<Video 1>/<Audio 1> and give every one an explicit job (identity, style, camera movement, voice character), stating which reference wins when two disagree. Use animate_photo with \"minimax-h3-i2v\" for a first-frame animation or \"minimax-h3-flf2v\" with frameRole=\"both\" for a first-to-last-frame transition. Seedance quality is selected only by model: use \"seedance2-mini\" for fast, lower-cost 720p Seedance draft iteration unless the user explicitly asks for legacy Fast, use \"seedance2-fast\" only when the user asks for Seedance Fast / seedance-fast, and use \"seedance2\" for the full Seedance 2.0 model, explicit non-fast/full-quality requests, 1080p/4K requests, or generated/uploaded storyboard images unless the user explicitly asks for a draft, Mini, or the fast model. Do not use Default Media Quality Fast/HQ/Pro or targetResolution to represent Seedance quality. Seedance supports multimodal loose reference assets. Seedance 2.0, Mini, and Fast accept images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total; Seedance 2.5 accepts images (up to 30), videos (up to 10), and audios (up to 10), with no more than 30 reference media files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices. \"seedance2-5\": Seedance 2.5, the newest Seedance generation — 480p and 720p ONLY (it cannot render 1080p or 4K), 4-30s per clip at a fixed 24 fps, native audio, and a much larger reference budget than Seedance 2.0: up to 30 images, 10 videos, and 10 audios, with no more than 30 reference media files in total. Seedance 2.5 covers text-to-video, image-to-video from a first frame, image-to-video with both a first and a last frame, and multimodal reference-to-video (including video editing and video extension). Pick \"seedance2-5\" when the user asks for Seedance 2.5, wants a single continuous Seedance clip longer than 15s (2.5 renders up to 30s natively instead of being split and stitched), or wants a first-and-last-frame Seedance transition. It does not replace \"seedance2\" for 1080p/4K requests, which Seedance 2.5 cannot satisfy. Seedance 2.5 is premium/subscriber-gated like the rest of the Seedance family."
     },
     "generateAudio": {
       "type": "boolean",
-      "description": "Seedance only. Whether Seedance should generate a native audio track. Omit by default; set false only when the user explicitly asks for silent output or no audio."
+      "description": "Whether to include generated/native audio for audio-capable models. Omit to include audio by default; set false only when the user explicitly asks for silent output or no audio. When false, the returned video has no audio track. Not supported by WAN or HappyHorse."
     },
     "referenceImageIndices": {
       "type": "array",
       "items": {
         "type": "number"
       },
-      "description": "Seedance only. Image references for @Image tags. Use negative indices for uploaded images (-1 first upload, -2 second upload) and non-negative indices for generated image results. Omit by default: uploaded images are auto-forwarded as @Image references. Anchor frame intent in the prompt with @Image tags: \"Use @Image1 as the opening shot reference. Begin the video with a composition, subject placement, lighting, mood, and camera framing that closely match @Image1.\" (or @Image2 as the final shot reference). For seamless-loop or \"first frame and last frame identical\" requests with a single uploaded image, anchor it explicitly as both: \"Use @Image1 as both the first frame and last frame so the video loops cleanly back to the opening composition.\" Do not use animate_photo sourceImageIndex/frameRole/endImageIndex for Seedance."
+      "description": "Image references for Seedance (@Image tags), HappyHorse 1.1 r2v, and MiniMax H3 r2v. Use negative indices for uploaded images (-1 first upload, -2 second upload) and non-negative indices for generated image results. For Seedance, omit by default: uploaded images are auto-forwarded as @Image references. Anchor frame intent in the prompt with @Image tags: \"Use @Image1 as the opening shot reference. Begin the video with a composition, subject placement, lighting, mood, and camera framing that closely match @Image1.\" (or @Image2 as the final shot reference). For seamless-loop or \"first frame and last frame identical\" requests with a single uploaded image, anchor it explicitly as both: \"Use @Image1 as both the first frame and last frame so the video loops cleanly back to the opening composition.\" Do not use animate_photo sourceImageIndex/frameRole/endImageIndex for Seedance. For HappyHorse 1.1 r2v, pass 1-9 image references. For MiniMax H3 r2v, up to 9 images are accepted; at least one image or video reference is required, and H3 references are loose references, not locked frames, and are addressed in the prompt as <Picture 1>, <Picture 2>, and so on in selection order."
     },
     "referenceVideoIndices": {
       "type": "array",
       "items": {
         "type": "number"
       },
-      "description": "Seedance only. Optional loose video references. Use negative indices for uploaded videos (-1 first uploaded video, -2 second uploaded video) and non-negative indices for generated video results. Omit by default: uploaded videos are auto-forwarded as @Video references. Set to choose a subset or include previously generated video URLs. Do not use this for uploaded source-video transforms, upscales, enhancements, restyles, or remasters; use video_to_video with controlMode=\"seedance-v2v\" instead."
+      "description": "Optional loose video references for Seedance and MiniMax H3 r2v. Use negative indices for uploaded videos (-1 first uploaded video, -2 second uploaded video) and non-negative indices for generated video results. For Seedance, omit by default: uploaded videos are auto-forwarded as @Video references. Set to choose a subset or include previously generated video URLs. Do not use this for uploaded source-video transforms, upscales, enhancements, restyles, or remasters; use video_to_video with controlMode=\"seedance-v2v\" instead. For MiniMax H3 r2v, up to 3 reference videos (24 fps, 2-15s each, optional soundtrack), addressed as <Video 1>, <Video 2>, and so on in selection order; they can satisfy the required visual reference without an image."
     },
     "referenceAudioIndices": {
       "type": "array",
       "items": {
         "type": "number"
       },
-      "description": "Seedance only. Optional loose audio references. Use negative indices for uploaded audio files (-1 first uploaded audio, -2 second uploaded audio) and non-negative indices for generated audio results. Omit by default: uploaded audio is auto-forwarded as @Audio references when the Seedance request also has an image or video reference. Use this only for loose background, mood, timing, or style references under an image/video-anchored Seedance shot. If the uploaded audio is the primary sync target, lip-sync target, or requested as sound-to-video/audio-sync, use sound_to_video with videoModel=\"seedance2\" instead. Audio-only Seedance requests are unsupported; use sound_to_video for uploaded-audio-only workflows."
+      "description": "Optional loose audio references for Seedance and MiniMax H3 r2v. Use negative indices for uploaded audio files (-1 first uploaded audio, -2 second uploaded audio) and non-negative indices for generated audio results. For Seedance, omit by default: uploaded audio is auto-forwarded as @Audio references when the Seedance request also has an image or video reference. Use this only for loose background, mood, timing, or style references under an image/video-anchored Seedance shot. If the uploaded audio is the primary sync target, lip-sync target, or requested as sound-to-video/audio-sync, use sound_to_video with videoModel=\"seedance2-mini\" instead unless the user asks for full Seedance. Audio-only Seedance requests are unsupported; use sound_to_video for uploaded-audio-only workflows. For MiniMax H3 r2v, up to 3 standalone audio tracks, addressed as <Audio 1>, <Audio 2>, and so on in selection order — a reference video's own soundtrack takes its Audio number before standalone tracks; they supplement a required image or video reference and cannot be the sole input."
     },
     "width": {
       "type": "number",
-      "description": "Video width in pixels. LTX 2.3: 640-3840. WAN: 480-1536. Default resolution depends on model and quality tier: LTX Fast about 720p and High/Pro about 1080p; WAN Fast uses 480p short side and High/Pro uses 720p short side. Set width only when the user specifies an exact width or orientation-qualified exact pixels. A bare named resolution like \"720p resolution\" is a short-side target, not an instruction to make landscape 1280x720. If the user gives only one exact dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested exact dimensions override the default media quality. Mappings when orientation is explicit: 480p landscape=854x480, 480p portrait=480x854, 720p landscape=1280x720, 720p portrait=720x1280, 1080p landscape=1920x1080, 1080p portrait=1080x1920, 4K landscape=3840x2160. Non-step values are accepted when in bounds; LTX snaps to the nearest 64px step and WAN snaps to the nearest 16px step internally, so do not ask the user to adjust by a few pixels."
+      "description": "Video width in pixels. LTX 2.5 and LTX 2.3: 640-3840. WAN: 480-1536. Default resolution depends on model and quality tier: LTX Fast about 720p and High/Pro about 1080p; WAN Fast uses 480p short side and High/Pro uses 720p short side. Set width only when the user specifies an exact width or orientation-qualified exact pixels. A bare named resolution like \"720p resolution\" is a short-side target, not an instruction to make landscape 1280x720. If the user gives only one exact dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested exact dimensions override the default media quality. Mappings when orientation is explicit: 480p landscape=854x480, 480p portrait=480x854, 720p landscape=1280x720, 720p portrait=720x1280, 1080p landscape=1920x1080, 1080p portrait=1080x1920, 4K landscape=3840x2160. Non-step values are accepted when in bounds; LTX snaps to the nearest 64px step and WAN snaps to the nearest 16px step internally, so do not ask the user to adjust by a few pixels."
     },
     "height": {
       "type": "number",
-      "description": "Video height in pixels. LTX 2.3: 640-3840. WAN: 480-1536. Set height only when the user specifies an exact height or orientation-qualified exact pixels. A bare named resolution like \"720p resolution\" is a short-side target; do not convert it to landscape dimensions unless the user says landscape/horizontal/widescreen. If the user gives only one exact dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested exact dimensions override Default Media Quality, including Pro. Non-step values are accepted when in bounds; LTX snaps to the nearest 64px step and WAN snaps to the nearest 16px step internally, so do not ask the user to adjust by a few pixels."
+      "description": "Video height in pixels. LTX 2.5 and LTX 2.3: 640-3840. WAN: 480-1536. Set height only when the user specifies an exact height or orientation-qualified exact pixels. A bare named resolution like \"720p resolution\" is a short-side target; do not convert it to landscape dimensions unless the user says landscape/horizontal/widescreen. If the user gives only one exact dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested exact dimensions override Default Media Quality, including Pro. Non-step values are accepted when in bounds; LTX snaps to the nearest 64px step and WAN snaps to the nearest 16px step internally, so do not ask the user to adjust by a few pixels."
     },
     "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. Also set for default Seedance 2.0 requests: 480 when Default Media Quality is Fast, otherwise 720, including Pro unless the user explicitly asks for 1080p or another resolution. For generated/uploaded storyboard images used as Seedance references, default to 720 even when Default Media Quality is Fast; only use 480 when the user explicitly asks for 480p. This preserves/inherits the current video shape instead of forcing landscape. 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 width/height/aspectRatio instead."
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This is resolution only, not a Seedance quality tier: Seedance quality is selected by videoModel (\"seedance2\" vs \"seedance2-mini\" vs \"seedance2-fast\" vs \"seedance2-5\"). Seedance 2.0 full supports 4K; Seedance Mini, Fast, and Seedance 2.5 support 480p/720p only, so never set 1080p or 4K for \"seedance2-5\". Do not set targetResolution from Default Media Quality Fast/HQ/Pro. If omitted for Seedance, the host uses the selected model default. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact width/height/aspectRatio instead."
     },
     "numberOfVariations": {
       "type": "number",
@@ -88,7 +98,7 @@
     },
     "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 described in the video (e.g. \"David\" narrates a scene featuring 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."
+      "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 described in the video (e.g. \"David\" narrates a scene featuring 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 because LTX 2.5 has no compatible ID-LoRA."
     }
   },
   "required": [

package/schemas/tools/replace_video_segment.schema.json

@@ -41,12 +41,15 @@
       "type": "string",
       "enum": [
         "auto",
+        "ltx25",
         "ltx23",
         "wan22",
         "seedance2",
-        "seedance2-fast"
+        "seedance2-mini",
+        "seedance2-fast",
+        "seedance2-5"
       ],
-      "description": "Which model to use for the new segment. Default: \"auto\" — detect from the base video's producer (Seedance base → Seedance, Wan base → Wan 2.2, otherwise LTX-2.3). Override only when the user explicitly requests a different model."
+      "description": "Which model to use for the new segment. Default: \"auto\" — preserve Seedance or WAN for matching base clips and otherwise use LTX 2.5. Use ltx23 only for explicit rollback. \"seedance2-5\" supports 480p/720p and 4-30s replacement windows at 24 fps."
     },
     "keepOriginalAudio": {
       "type": "boolean",

package/schemas/tools/sound_to_video.schema.json

@@ -3,25 +3,29 @@
   "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/sound_to_video.schema.json",
   "title": "sound_to_video arguments",
   "schemaVersion": "2026-04-27.1",
-  "description": "Generate video synchronized to audio. Use when the user has uploaded an audio file (mp3, wav, m4a, flac) and the audio is the primary sync target, especially uploaded-audio-only workflows. Also use after generate_music (\"turn that song into a video\", \"make a music video from that\"). Auto-detects generated audio from generate_music if no audio file is uploaded. Seedance animate_photo/generate_video can also attach uploaded audio as a loose @Audio reference when an image or video reference anchors the request; use this tool instead when the soundtrack itself should drive the video. If the user provides a reference image, use ltx23-ia2v; for lip-sync with a face image, use wan-s2v; if no image, use ltx23-a2v. If the user wants dialogue/audio WITHOUT pre-existing audio, use animate_photo instead (LTX 2.3 generates audio natively). Note: Persona voice clips from resolve_personas are NOT used by this tool — for persona voice identity in video, use animate_photo or generate_video instead. LONG AUDIO ON SEEDANCE: Seedance caps each clip at 15s. When the user uploads audio longer than 15s and Seedance is selected (seedance2 or seedance2-fast), do NOT clamp to 15s and drop the rest — split the run into multiple sound_to_video calls in the same turn (one per 15s segment, so a 20s audio becomes two clips: audioStart=0 duration=15, then audioStart=15 duration=5) and finish with a single stitch_video call referencing the resulting clip indices in order with audioIndex pointing at the same uploaded audio so the stitched output carries the full original soundtrack. LTX/WAN models accept up to 20s per clip, so single-call is fine for them.",
+  "description": "Generate video synchronized to audio. Use when the user has uploaded an audio file (mp3, wav, m4a, flac) and the audio is the primary sync target, especially uploaded-audio-only workflows. Also use after generate_music (\"turn that song into a video\", \"make a music video from that\"). Auto-detects generated audio from generate_music if no audio file is uploaded. Seedance animate_photo/generate_video can also attach uploaded audio as a loose @Audio reference when an image or video reference anchors the request; use this tool instead when the soundtrack itself should drive the video. If the user provides a reference image, use ltx25-ia2v by default (ltx23-ia2v is rollback); for lip-sync with a face image, use wan-s2v; if no image, use ltx25-a2v by default (ltx23-a2v is rollback). If the user wants dialogue/audio WITHOUT pre-existing audio, use animate_photo instead (LTX 2.5 and LTX 2.3 generate audio natively). Note: Persona voice clips from resolve_personas are NOT used by this tool — for persona voice identity in video, use animate_photo or generate_video with videoModel=\"ltx23\" because LTX 2.5 has no compatible ID-LoRA. LONG AUDIO ON SEEDANCE: Seedance 2.0, Mini, and Fast cap each clip at 15s; Seedance 2.5 caps each clip at 30s, so prefer \"seedance2-5\" for 16-30s audio instead of splitting. When uploaded audio exceeds the selected Seedance model's per-clip cap, do NOT clamp and drop the rest — split the run into multiple sound_to_video calls in the same turn using 15s segments for seedance2/seedance2-mini/seedance2-fast or 30s segments for seedance2-5, then finish with a single stitch_video call referencing the resulting clip indices in order with audioIndex pointing at the same uploaded audio so the stitched output carries the full original soundtrack. LTX/WAN models accept up to 20s per clip, so single-call is fine for them.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "prompt": {
       "type": "string",
-      "description": "Describe the video like a cinematographer. Let the audio define timing — use the prompt for visual interpretation. One flowing paragraph, present tense, specific natural language.\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. For Seedance, set expandPrompt=false.\n\nSTRUCTURE: shot/style and scale → subject → environment, lighting, color, texture, atmosphere → visual action synced to audio → camera movement. For LTX 2.3 image+audio mode, do not re-describe static details already visible in the reference image; focus on motion, action, camera, and how the image responds to the audio.\n\nMOTION PACING: Scale complexity to duration. <=6s: 1 main visual beat + 1 simple camera move. Around 10s: 2-3 clear beats + 1 camera move. >10s: up to 4 beats in clear sequence. Let the audio define timing, but avoid stacking subject, camera, and environment motion in short clips.\n\nBLOCKING: Direct layout when it affects the shot: left/right placement, foreground/background, facing direction, and relative distance between subjects.\n\nLIP-SYNC: Shot framing, speaker's appearance and setting, physical performance synced to audio — gestures, expressions, jaw movement between phrases. Include acting beats.\n\nMUSIC VISUALIZATION: Visual style, environment, and how elements react to rhythm and energy.\n\nAUDIO-REACTIVE: Motion and visual changes that correspond to sounds in the track.\n\nLTX VOCABULARY: camera (tracking, dolly, pan, tilt, handheld, static frame), lighting/atmosphere (golden hour, neon glow, dramatic shadows, fog, rain, smoke, reflections), scale/pacing (expansive, epic, intimate, claustrophobic, slow motion, time-lapse, lingering shot, continuous shot), style/genre (film noir, painterly, cyberpunk, stop-motion, claymation, 2D/3D animation, hand-drawn, fantasy, thriller, experimental film).\n\nAVOID: Vague prompts, too many competing visual elements, abstract descriptions without visible behavior, rigid numeric constraints, readable text or logos. 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.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary the visual interpretation while keeping audio sync intent consistent. Example: \"{abstract neon visualization|nature scene with swaying trees|urban street with rain} synced to the beat\"."
+      "description": "Describe the video like a cinematographer. Let the audio define timing — use the prompt for visual interpretation. One flowing paragraph, present tense, specific natural language.\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. For Seedance, set expandPrompt=false.\n\nSTRUCTURE: shot/style and scale → subject → environment, lighting, color, texture, atmosphere → visual action synced to audio → camera movement. For LTX 2.5 or LTX 2.3 image+audio mode, do not re-describe static details already visible in the reference image; focus on motion, action, camera, and how the image responds to the audio.\n\nMOTION PACING: Scale complexity to duration. <=6s: 1 main visual beat + 1 simple camera move. Around 10s: 2-3 clear beats + 1 camera move. >10s: up to 4 beats in clear sequence. Let the audio define timing, but avoid stacking subject, camera, and environment motion in short clips.\n\nBLOCKING: Direct layout when it affects the shot: left/right placement, foreground/background, facing direction, and relative distance between subjects.\n\nLIP-SYNC: Shot framing, speaker's appearance and setting, physical performance synced to audio — gestures, expressions, jaw movement between phrases. Include acting beats.\n\nMUSIC VISUALIZATION: Visual style, environment, and how elements react to rhythm and energy.\n\nAUDIO-REACTIVE: Motion and visual changes that correspond to sounds in the track.\n\nLTX VOCABULARY: camera (tracking, dolly, pan, tilt, handheld, static frame), lighting/atmosphere (golden hour, neon glow, dramatic shadows, fog, rain, smoke, reflections), scale/pacing (expansive, epic, intimate, claustrophobic, slow motion, time-lapse, lingering shot, continuous shot), style/genre (film noir, painterly, cyberpunk, stop-motion, claymation, 2D/3D animation, hand-drawn, fantasy, thriller, experimental film).\n\nAVOID: Vague prompts, too many competing visual elements, abstract descriptions without visible behavior, rigid numeric constraints, readable text or logos. 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.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary the visual interpretation while keeping audio sync intent consistent. Example: \"{abstract neon visualization|nature scene with swaying trees|urban street with rain} synced to the beat\"."
     },
     "expandPrompt": {
       "type": "boolean",
       "description": "Seedance only. Whether to run the shared Seedance prompt shaper before dispatch. Defaults to true; set false only when the user explicitly asks to submit the compact prompt directly or not modify the prompt."
     },
+    "negativePrompt": {
+      "type": "string",
+      "description": "Advanced LTX 2.5/LTX 2.3/WAN only. The LTX A2V and IA2V workflows accept this separate negative prompt. Use it only when the user explicitly asks to set one. Do not set for Seedance."
+    },
     "audioSourceIndex": {
       "type": "number",
       "description": "Index of the uploaded audio file to use (0-based, from uploaded files list). If only one audio file is uploaded, use 0. If no audio was uploaded but generate_music was used earlier, omit this — the tool will automatically find the generated audio."
     },
     "sourceImageIndex": {
       "type": "number",
-      "description": "Optional index of an uploaded image to use as the starting frame (0-based). Required for lip-sync models (WAN S2V). For audio-only-to-video models (LTX 2.3 A2V), this is optional — omit it to generate video purely from text + audio."
+      "description": "Optional index of an uploaded image to use as the starting frame (0-based). Required for lip-sync models (WAN S2V). For audio-only-to-video models (LTX 2.5 or LTX 2.3 A2V), this is optional — omit it to generate video purely from text + audio."
     },
     "audioStart": {
       "type": "number",
@@ -30,24 +34,28 @@
     },
     "duration": {
       "type": "number",
-      "description": "Video duration in seconds. Default: 5. Range: 2-20. For music videos, use the MAXIMUM duration (20) since the audio is always longer than the video limit. Use when the user explicitly requests a specific length.",
+      "description": "Video duration in seconds. Default: 5. Range: 2-30; the usable window is per-model and the host clamps to it. LTX 2.5, LTX 2.3, and WAN accept 2-20, Seedance 2.0/Mini/Fast accept 4-15, and Seedance 2.5 accepts 4-30. For music videos, use the MAXIMUM duration the selected model allows (20 for LTX/WAN, 30 for \"seedance2-5\") since the audio is always longer than the video limit. Use when the user explicitly requests a specific length.",
       "minimum": 2,
-      "maximum": 20
+      "maximum": 30
     },
     "videoModel": {
       "type": "string",
       "enum": [
         "wan-s2v",
         "seedance2",
+        "seedance2-mini",
         "seedance2-fast",
+        "seedance2-5",
+        "ltx25-ia2v",
+        "ltx25-a2v",
         "ltx23-ia2v",
         "ltx23-a2v"
       ],
-      "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast (720p cap) — pick this whenever the user says \"Seedance fast\", \"seedance-fast\", or asks for 480p/720p; pick \"seedance2\" only when they explicitly request 1080p or the full Seedance variant. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
+      "description": "Video model. \"ltx25-ia2v\" (default when image available) and \"ltx25-a2v\" (default without an image) use LTX 2.5; Fast/HQ use official distilled INT8 and Pro uses dev INT8 with the required official distilled Speed LoRA in stage 2. \"ltx23-ia2v\" and \"ltx23-a2v\" retain the LTX 2.3 rollback paths with their existing quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": full Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-mini\": Seedance 2.0 Mini for faster, lower-cost 720p iteration. \"seedance2-fast\": legacy Seedance 2.0 Fast. Seedance quality is selected only by this model value: pick \"seedance2-mini\" for faster draft/lower-cost Seedance unless the user explicitly says Seedance Fast, pick \"seedance2-fast\" when the user says Seedance Fast / seedance-fast, and pick \"seedance2\" for full/non-fast Seedance or 1080p/4K. Do not infer the Seedance model from Default Media Quality Fast/HQ/Pro. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present. \"seedance2-5\": Seedance 2.5, the newest Seedance generation — 480p and 720p ONLY (it cannot render 1080p or 4K), 4-30s per clip at a fixed 24 fps, native audio, and a much larger reference budget than Seedance 2.0: up to 30 images, 10 videos, and 10 audios, with no more than 30 reference media files in total. Seedance 2.5 covers text-to-video, image-to-video from a first frame, image-to-video with both a first and a last frame, and multimodal reference-to-video (including video editing and video extension). Pick \"seedance2-5\" when the user asks for Seedance 2.5, wants a single continuous Seedance clip longer than 15s (2.5 renders up to 30s natively instead of being split and stitched), or wants a first-and-last-frame Seedance transition. It does not replace \"seedance2\" for 1080p/4K requests, which Seedance 2.5 cannot satisfy. Seedance 2.5 is premium/subscriber-gated like the rest of the Seedance family."
     },
     "generateAudio": {
       "type": "boolean",
-      "description": "Seedance only. Whether Seedance should include a generated/native audio track in the final video. Omit by default so the reference audio drives the result; set false only for explicit silent output."
+      "description": "Whether the final video should include audio. Omit to include audio by default; set false when the user asks for silent output or no audio. When false, the returned video has no audio track; the reference audio is still required and still drives generation."
     },
     "numberOfVariations": {
       "type": "number",
@@ -57,7 +65,7 @@
     },
     "targetResolution": {
       "type": "number",
-      "description": "Short-side video resolution target in pixels. Use ONLY 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/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
     },
     "aspectRatio": {
       "type": "string",

package/schemas/tools/tool-metadata.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/tools/tool-metadata.schema.json",
+  "title": "Tool catalog metadata",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Metadata that accompanies each tool definition in the v2 catalog. Drives tool surfacing decisions (which family/execution mode is visible this turn), spend gating (costClass + requiresConfirmation), retry behavior (retrySafety), and durable-run observability (mutatesData, producesArtifacts). Input/output schema refs point at sogni-protocol argument and result contracts so the validator and the planner share one source of truth.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Canonical tool name (snake_case, matches the OpenAI-format tool definition exposed to the LLM)."
+    },
+    "family": {
+      "type": "string",
+      "enum": ["creative", "composition", "artifact", "memory", "settings", "analysis", "control"],
+      "description": "Coarse grouping used by the planner to pick a minimal visible tool subset."
+    },
+    "executionMode": {
+      "type": "string",
+      "enum": ["hosted", "client", "app", "workflow", "internal"],
+      "description": "Where the tool runs. 'hosted' = sogni-api durable runner. 'client' = browser tool dispatch. 'app' = native shell. 'workflow' = synthetic tool that creates a WorkflowRun. 'internal' = runtime-only (e.g. L1 hidden resolver) — never surfaced to the LLM directly."
+    },
+    "inputSchemaRef": {
+      "type": "string",
+      "description": "URI or repo-relative path. MUST resolve to a sogni-protocol tool argument JSON Schema (e.g. schemas/tools/generate_image.schema.json)."
+    },
+    "outputSchemaRef": {
+      "type": "string",
+      "description": "URI or repo-relative path. MUST resolve to a sogni-protocol tool result envelope schema."
+    },
+    "costClass": {
+      "type": "string",
+      "enum": ["free", "low", "medium", "high", "variable"],
+      "description": "Indicative cost tier. Concrete unit estimates live on the SpendGate request, not here."
+    },
+    "latencyClass": {
+      "type": "string",
+      "enum": ["inline", "interactive", "long_running"],
+      "description": "Indicative wall-clock tier. 'long_running' tools generally belong inside a Workflow Template, not a synchronous chat turn."
+    },
+    "mutatesData": {
+      "type": "boolean",
+      "description": "True when the tool changes persisted user state (e.g. manage_memory write, settings update)."
+    },
+    "producesArtifacts": {
+      "type": "boolean",
+      "description": "True when the tool emits one or more ArtifactNodes that must be registered in the ArtifactGraph."
+    },
+    "requiresConfirmation": {
+      "type": "string",
+      "enum": ["never", "paid", "destructive", "always"],
+      "description": "Confirmation policy. 'paid' defers to SpendGate. 'destructive' requires an explicit user yes regardless of cost. 'always' is reserved for atomic operations with no other gate."
+    },
+    "retrySafety": {
+      "type": "string",
+      "enum": ["idempotent", "dedupe_key_required", "not_safe"],
+      "description": "Whether the runner may retry the tool call on a transient failure. 'dedupe_key_required' tools must be called with a stable dedupe token (e.g. sogni-socket project id)."
+    },
+    "hiddenFromModel": {
+      "type": "boolean",
+      "description": "Optional. L1 hidden context tools (resolve_*, inspect_*) set this true so the runner can call them directly without surfacing them to the LLM."
+    }
+  },
+  "required": [
+    "name",
+    "family",
+    "executionMode",
+    "inputSchemaRef",
+    "outputSchemaRef",
+    "costClass",
+    "latencyClass",
+    "mutatesData",
+    "producesArtifacts",
+    "requiresConfirmation",
+    "retrySafety"
+  ]
+}

package/schemas/tools/upscale_image.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-07-18.1/tools/upscale_image.schema.json",
+  "title": "upscale_image arguments",
+  "schemaVersion": "2026-07-18.1",
+  "description": "Enlarge an existing image with NVIDIA RTX Video Super Resolution while preserving its content, identity, composition, and colors. This is deterministic reconstruction, not a generative edit: it takes no prompt and must not be used for restoration, sharpening requests that imply repainting, object changes, style changes, or creative enhancement. Use it when the user asks to upscale, enlarge, increase resolution, prepare for print, or produce a 2K/4K/6K/8K copy without changing the image.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "sourceImageIndex": {
+      "type": "number",
+      "description": "Source image to upscale. Non-negative values select a prior generated result by 0-based index. Negative values select uploads: -1 is the first uploaded image, -2 the second, and so on. If omitted, use the latest generated image, falling back to the first upload."
+    },
+    "scale": {
+      "type": "number",
+      "enum": [
+        2,
+        3,
+        4
+      ],
+      "description": "Edge scale multiplier. Use 2 by default. Ignored when targetLongestEdge is supplied. If that scale would leave either aligned output edge below 512px, the tool reports the minimum valid target instead of stretching the image."
+    },
+    "targetLongestEdge": {
+      "type": "number",
+      "minimum": 512,
+      "maximum": 8192,
+      "description": "Optional requested pixel length for the output longest edge, from 512 through 8192. Use 3840 for 4K UHD, 6144 for 6K, 7680 for 8K UHD, or 8192 for an 8K-class maximum. The other edge is calculated automatically so the source aspect ratio is preserved; both aligned output edges must be at least 512px."
+    }
+  },
+  "required": []
+}

package/schemas/tools/video_to_video.schema.json

@@ -3,13 +3,13 @@
   "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/video_to_video.schema.json",
   "title": "video_to_video arguments",
   "schemaVersion": "2026-04-27.1",
-  "description": "Transform an existing video using AI. Uses WAN 2.2 Animate (move/replace) with a reference image to animate a photo with the video's motion or swap the video's subject, LTX-2.3 V2V ControlNet (canny/pose/depth/detailer) for video-only transforms, or Seedance V2V when the user explicitly asks to transform, upscale, enhance, restyle, or remaster an uploaded video with Seedance. Requires an uploaded video file. Use when the user wants to animate a photo with video motion, replace subjects in a video, restyle an existing video, or enhance video quality.",
+  "description": "Transform an existing video using WAN 2.2 Animate, LTX 2.5 V2V controls by default, LTX 2.3 as rollback, or Seedance V2V when explicitly requested. LTX 2.5 distilled supports canny/pose/depth/detailer/inpaint/outpaint; Dev + Speed LoRA supports canny/pose/depth/detailer. Requires an uploaded video.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "prompt": {
       "type": "string",
-      "description": "Describe the TARGET appearance (not the transformation process). 2-4 present-tense 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. For Seedance, set expandPrompt=false.\n\nFor LTX-2.3 canny/depth/pose modes, the source video preserves composition, depth, or motion. Spend prompt detail on style, atmosphere, lighting, surface texture, color palette, scale, and pacing.\n\nExamples by mode:\n- animate-move (DEFAULT — WAN 2.2 Animate Move: applies camera/motion from source video to reference image): \"Smooth cinematic camera movement following the subject through the scene.\"\n- animate-replace (WAN 2.2 Animate Replace: replaces the subject in the source video with the reference image): \"The person from the reference photo performing the actions from the video.\"\n- canny (LTX-2.3 — edge-detection restyle): \"Hand-drawn watercolor anime style with soft ink edges, muted teal and coral palette, rain mist, neon reflections, warm rim light, preserving original silhouettes and composition.\"\n- pose (LTX-2.3 — tracks skeleton, replace person): \"A glossy cartoon robot with exaggerated proportions, brushed metal texture, glowing cyan joints, energetic stage lighting, preserving the original dance timing and pose.\"\n- depth (LTX-2.3 — depth-map restyle): \"A misty alpine valley at golden hour, expansive scale, volumetric haze, cool blue shadows, warm rim light, cinematic depth, lingering continuous shot.\"\n- detailer (LTX-2.3 — enhance quality): DESCRIBE THE SOURCE, do not request changes. Append quality qualifiers only. E.g. \"The same scene, ultra-sharp and clean, crisp high-resolution detail, preserving all original content, composition, and color.\" Avoid words like \"enhanced textures\", \"restyled\", or any new subjects/objects — they cause drift.\n- seedance-v2v (BytePlus Dreamina Seedance 2.0 V2V): \"Restyle the source clip in a watercolor look with soft ink edges, while preserving its motion and composition.\" Use natural prose; Seedance reads the reference video holistically rather than via control-net constraints, so describe target style/mood/dialogue rather than control strength.\n\nPresent tense. Positive phrasing. Concrete visual details.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary the artistic treatment while keeping control mode and structural intent consistent. Example: \"transform to {watercolor with soft edges|oil painting with bold strokes|anime with clean lines} style\"."
+      "description": "Describe the TARGET appearance, motion, dialogue, audio, and style in positive present-tense language. For LTX 2.5 (default) or LTX 2.3 rollback canny/depth/pose modes, the source preserves the selected structure or motion, so emphasize style, atmosphere, lighting, texture, color, scale, and pacing. Canny preserves edges; pose preserves skeletal motion; depth preserves 3D layout; detailer should describe the original content with quality qualifiers only. Distilled LTX 2.5 also supports inpaint and outpaint; Dev + Speed LoRA does not. For inpaint, describe only the regenerated region. For outpaint, describe the newly revealed area consistently with the source. For Seedance V2V, use natural prose and describe the target transformation holistically."
     },
     "expandPrompt": {
       "type": "boolean",
@@ -30,29 +30,32 @@
         "detailer",
         "seedance-v2v"
       ],
-      "description": "How the source video and (optional) reference image interact. Pick by user intent:\n• \"animate-move\" (DEFAULT) — WAN 2.2 Animate Move. Applies camera movement and motion from the source video to the reference image, bringing a still photo to life. Requires sourceImageIndex.\n• \"animate-replace\" — WAN 2.2 Animate Replace. Replaces the subject in the source video with the person/character from the reference image, keeping the video's background and motion. Requires sourceImageIndex.\n• \"canny\" — LTX-2.3 edge-detection control. Best for restyling while preserving exact composition and silhouettes (e.g. \"make this footage look like anime / oil painting / watercolor\"). Use for subjects with crisp edges — people, objects, graphics. Video-only; no reference image needed.\n• \"pose\" — LTX-2.3 skeletal tracking. Best for replacing a person while keeping their motion (e.g. \"turn this dancer into a robot\"). Image optional — if provided, controls appearance; otherwise the prompt drives appearance. Requires person-centric motion.\n• \"depth\" — LTX-2.3 depth-map control. Best for restyling scenes with perspective, camera movement, or volumetric content (landscapes, interiors, camera pans). Preserves 3D spatial layout rather than 2D edges; more forgiving than canny when edges are noisy. Video-only.\n• \"detailer\" — LTX-2.3 quality enhancement. Sharpens detail and texture WITHOUT restyling. The prompt must DESCRIBE THE ORIGINAL scene with quality qualifiers (sharp, clean, high-resolution) — never request content changes, new textures, or a new look. Pick this when the user asks to \"improve quality\", \"enhance\", \"upscale\", or \"sharpen\" without a creative transformation.\n• \"seedance-v2v\" — BytePlus Dreamina Seedance 2.0 video-to-video. Use only when the user explicitly asks for Seedance on the uploaded source video, such as Seedance Fast upscale, enhance, remaster, restyle, or transform. High-fidelity quality, native audio, time-coded scene control. Seedance V2V reads @Video1 holistically. Use it for restyling, motion transfer, extension, subject replacement, or scene transformation, and assign @Video1 a clear role such as source clip, camera movement, action timing, edit rhythm, or continuation anchor. Distinct from canny/depth/pose which use control-net constraints — Seedance treats the reference video holistically.\nCanny vs depth: canny preserves silhouettes and fine outlines — pick it for subject-led scenes and graphic restyles. Depth preserves 3D structure — pick it for scenes where the camera moves or spatial layout matters more than edge fidelity. Default: \"animate-move\"."
+      "description": "How the source video and (optional) reference image interact. Pick by user intent:\n• \"animate-move\" (DEFAULT) — WAN 2.2 Animate Move. Applies camera movement and motion from the source video to the reference image, bringing a still photo to life. Requires sourceImageIndex.\n• \"animate-replace\" — WAN 2.2 Animate Replace. Replaces the subject in the source video with the person/character from the reference image, keeping the video's background and motion. Requires sourceImageIndex.\n• \"canny\" — LTX-2.3 edge-detection control. Best for restyling while preserving exact composition and silhouettes (e.g. \"make this footage look like anime / oil painting / watercolor\"). Use for subjects with crisp edges — people, objects, graphics. Video-only; no reference image needed.\n• \"pose\" — LTX-2.3 skeletal tracking. Best for replacing a person while keeping their motion (e.g. \"turn this dancer into a robot\"). Image optional — if provided, controls appearance; otherwise the prompt drives appearance. Requires person-centric motion.\n• \"depth\" — LTX-2.3 depth-map control. Best for restyling scenes with perspective, camera movement, or volumetric content (landscapes, interiors, camera pans). Preserves 3D spatial layout rather than 2D edges; more forgiving than canny when edges are noisy. Video-only.\n• \"detailer\" — LTX-2.3 quality enhancement. Sharpens detail and texture WITHOUT restyling. The prompt must DESCRIBE THE ORIGINAL scene with quality qualifiers (sharp, clean, high-resolution) — never request content changes, new textures, or a new look. Pick this when the user asks to \"improve quality\", \"enhance\", \"upscale\", or \"sharpen\" without a creative transformation.\n• \"seedance-v2v\" — BytePlus Dreamina Seedance video-to-video. Use only when the user explicitly asks for Seedance on the uploaded source video, such as Seedance Fast upscale, enhance, remaster, restyle, or transform. High-fidelity quality, native audio, time-coded scene control. Seedance V2V reads @Video1 holistically. Use it for restyling, motion transfer, extension, subject replacement, or scene transformation, and assign @Video1 a clear role such as source clip, camera movement, action timing, edit rhythm, or continuation anchor. Distinct from canny/depth/pose which use control-net constraints — Seedance treats the reference video holistically.\nCanny vs depth: canny preserves silhouettes and fine outlines — pick it for subject-led scenes and graphic restyles. Depth preserves 3D structure — pick it for scenes where the camera moves or spatial layout matters more than edge fidelity. Default: \"animate-move\"."
     },
     "negativePrompt": {
       "type": "string",
-      "description": "Non-Seedance only. Optional negative prompt for LTX/Wan video-to-video models. Do not set when controlMode is seedance-v2v or videoModel is seedance2/seedance2-fast; rewrite user-provided Seedance avoid/ban/no-X requests as positive prompt instructions."
+      "description": "Non-Seedance only. Optional negative prompt supported by every LTX 2.5 and LTX 2.3 video-to-video control/edit template, plus WAN. Do not set when controlMode is seedance-v2v or videoModel is seedance2/seedance2-mini/seedance2-fast/seedance2-5; rewrite user-provided Seedance avoid/ban/no-X requests as positive prompt instructions."
     },
     "videoModel": {
       "type": "string",
       "enum": [
+        "ltx25-v2v",
         "ltx23-v2v",
         "wan22-animate",
         "seedance2",
-        "seedance2-fast"
+        "seedance2-mini",
+        "seedance2-fast",
+        "seedance2-5"
       ],
-      "description": "Model selector for this video-to-video request. Usually omit; controlMode chooses the non-Seedance model. For controlMode=\"seedance-v2v\", use \"seedance2-fast\" by default, especially when the user asks for Seedance Fast/seedance-fast or 480p/720p. Use \"seedance2\" only when the user explicitly asks for the full/non-fast Seedance model or 1080p."
+      "description": "Model selector for this video-to-video request. Usually omit; controlMode chooses the non-Seedance model. \"ltx25-v2v\" is the default LTX 2.5 control path; \"ltx23-v2v\" remains the rollback selector. For controlMode=\"seedance-v2v\", Seedance quality is selected only by model: use \"seedance2-mini\" for fast, lower-cost 720p Seedance V2V unless the user explicitly asks for legacy Fast, use \"seedance2-fast\" when the user asks for Seedance Fast / seedance-fast, and use \"seedance2\" for full/non-fast Seedance or 1080p/4K. Do not infer the Seedance model from Default Media Quality Fast/HQ/Pro or from 480p/720p resolution requests alone. \"seedance2-5\": Seedance 2.5, the newest Seedance generation — 480p and 720p ONLY (it cannot render 1080p or 4K), 4-30s per clip at a fixed 24 fps, native audio, and a much larger reference budget than Seedance 2.0: up to 30 images, 10 videos, and 10 audios, with no more than 30 reference media files in total. Seedance 2.5 covers text-to-video, image-to-video from a first frame, image-to-video with both a first and a last frame, and multimodal reference-to-video (including video editing and video extension). Pick \"seedance2-5\" when the user asks for Seedance 2.5, wants a single continuous Seedance clip longer than 15s (2.5 renders up to 30s natively instead of being split and stitched), or wants a first-and-last-frame Seedance transition. It does not replace \"seedance2\" for 1080p/4K requests, which Seedance 2.5 cannot satisfy. Seedance 2.5 is premium/subscriber-gated like the rest of the Seedance family."
     },
     "generateAudio": {
       "type": "boolean",
-      "description": "Seedance V2V only. Whether Seedance should generate/retain a native audio track. Omit by default; set false only when the user explicitly asks for silent output or no audio. Use only with controlMode=\"seedance-v2v\"."
+      "description": "Whether the final video should include generated or retained audio. Omit to include audio by default; set false when the user asks for silent output or no audio. When false, the returned video has no audio track."
     },
     "targetResolution": {
       "type": "number",
-      "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact dimensions. For Seedance V2V fast, 480p and 720p are supported; preserve the source video shape instead of forcing landscape pixels."
+      "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact dimensions. Seedance V2V full supports 4K; Seedance V2V Mini, Fast, and Seedance 2.5 support 480p and 720p only, so never set 1080p or 4K for \"seedance2-5\". Preserve the source video shape instead of forcing landscape pixels."
     },
     "sourceImageIndex": {
       "type": "number",
@@ -60,9 +63,9 @@
     },
     "duration": {
       "type": "number",
-      "description": "Output video duration in seconds. Range: 2-20 for WAN/LTX modes and 4-15 for controlMode=\"seedance-v2v\". If omitted, the tool matches the uploaded source video duration when available (capped to the selected model range); otherwise it falls back to 10s for WAN Animate Move/Replace and 5s for LTX-2.3/Seedance modes. For long stitched/bulk WAN Animate Move/Replace work with no explicit per-clip length, prefer about 10s clips rather than 5s chunks. Only pass this when the user explicitly requests a different length.",
+      "description": "Output video duration in seconds. Range: 2-20 for WAN/LTX modes, 4-15 for controlMode=\"seedance-v2v\" on \"seedance2\"/\"seedance2-mini\"/\"seedance2-fast\", and 4-30 for controlMode=\"seedance-v2v\" on \"seedance2-5\". If omitted, the tool matches the uploaded source video duration when available (capped to the selected model range); otherwise it falls back to 10s for WAN Animate Move/Replace and 5s for LTX-2.3/Seedance modes. For long stitched/bulk WAN Animate Move/Replace work with no explicit per-clip length, prefer about 10s clips rather than 5s chunks. Only pass this when the user explicitly requests a different length.",
       "minimum": 2,
-      "maximum": 20
+      "maximum": 30
     },
     "numberOfVariations": {
       "type": "number",

package/schemas/workflows/durable-workflow-run.schema.json

@@ -38,6 +38,7 @@
               "edit_image",
               "apply_style",
               "restore_photo",
+              "upscale_image",
               "refine_result",
               "animate_photo",
               "change_angle",

package/version.json

@@ -1,4 +1,4 @@
 {
-  "protocolVersion": "1.1.0",
+  "protocolVersion": "1.13.0",
   "description": "Sogni protocol artifact version. SDKs may refuse to operate against a protocolVersion they were not built for. Bump the major when removing or renaming any schema / enum / manifest field; bump the minor when adding new optional fields or new tools; bump the patch for description / prose changes only."
 }