@sogni-ai/sogni-creative-agent-skill 2.1.2 → 2.2.0

package/sogni-agent.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 /**
- * sogni-agent - Generate images and videos using Sogni AI
+ * sogni-agent - Generate images, videos, and music using Sogni AI
  * Usage: sogni-agent [options] "prompt"
  */
 
-import { SogniClientWrapper, ClientEvent, getMaxContextImages } from '@sogni-ai/sogni-client-wrapper';
+import { SogniClientWrapper, ClientEvent, getMaxContextImages as getWrapperMaxContextImages } from '@sogni-ai/sogni-client-wrapper';
 import JSON5 from 'json5';
 import { createHash, randomBytes } from 'crypto';
+import { createRequire } from 'module';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, mkdtempSync, statSync, readdirSync, realpathSync, lstatSync, unlinkSync, rmdirSync } from 'fs';
 import { join, dirname, basename, extname, sep } from 'path';
 import { homedir, tmpdir } from 'os';
@@ -17,7 +18,11 @@ import { assertSafeUrl } from './ssrf-guard.mjs';
 import {
   LTX23_WORKFLOW_MODELS,
   QUALITY_TIERS,
+  SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS,
   VIDEO_WORKFLOW_DEFAULT_MODELS,
+  buildStoryboardVideoHostedToolSequenceInput,
+  detectReferenceAudioFormat,
+  dimensionsForAspectRatio,
   dimensionsWithShortSide,
   getModelDefaults,
   getVideoPromptGuardrailPlan,
@@ -25,6 +30,7 @@ import {
   inferVideoWorkflowFromModel,
   isLtx2Model,
   isSeedanceModel,
+  isSeedanceModelSelection,
   normalizeVideoWorkflow,
   planCliVideoBrain,
   resolveVideoControlNetStrength,
@@ -32,9 +38,13 @@ import {
   resolveVideoSteps,
   sanitizeBatchPrompt,
   selectDefaultVideoModel,
+  shouldTrimSeedanceV2VSourceVideo,
   workflowRequiresImage
 } from './generated/creative-agent-runtime.mjs';
 
+const require = createRequire(import.meta.url);
+const { parseCreativeWorkflowSseChunk } = require('@sogni-ai/sogni-client-wrapper');
+
 // ---------------------------------------------------------------------------
 // Path sanitization — defense-in-depth for any value that becomes a file path
 // or process argument. execaSync runs argument arrays without shell expansion,
@@ -76,11 +86,48 @@ const DEFAULT_MEMORIES_PATH = join(homedir(), '.config', 'sogni', 'memories.json
 const DEFAULT_PERSONALITY_PATH = join(homedir(), '.config', 'sogni', 'personality.txt');
 const DEFAULT_PERSONAS_DIR = join(homedir(), '.config', 'sogni', 'personas');
 const DEFAULT_PERSONAS_INDEX_PATH = join(homedir(), '.config', 'sogni', 'personas', 'index.json');
+const DEFAULT_API_BASE_URL = 'https://api.sogni.ai';
+const DEFAULT_SAFE_API_HOSTS = Object.freeze(['api.sogni.ai']);
+const LOOPBACK_API_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1']);
+const DEFAULT_LLM_MODEL = 'qwen3.6-35b-a3b-gguf-iq4xs';
+const SOGNI_APP_SOURCE = 'sogni-creative-agent-skill';
 const OPENCLAW_CONFIG_PATH = getEnv('OPENCLAW_CONFIG_PATH') || DEFAULT_OPENCLAW_CONFIG_PATH;
 const IS_OPENCLAW_INVOCATION = Boolean(getEnv('OPENCLAW_PLUGIN_CONFIG'));
 const RAW_ARGS = process.argv.slice(2);
 const CLI_WANTS_JSON = RAW_ARGS.includes('--json');
 const JSON_ERROR_MODE = CLI_WANTS_JSON || IS_OPENCLAW_INVOCATION;
+const SOCKET_EVENT_SUBSCRIPTIONS = Object.freeze({
+  modelAvailability: false
+});
+const MUSIC_MODEL_IDS = {
+  turbo: 'ace_step_1.5_turbo',
+  speed: 'ace_step_1.5_turbo',
+  fast: 'ace_step_1.5_turbo',
+  sft: 'ace_step_1.5_sft',
+  lyrics: 'ace_step_1.5_sft',
+  lyric: 'ace_step_1.5_sft'
+};
+const MUSIC_MODEL_DEFAULTS = {
+  'ace_step_1.5_turbo': {
+    steps: { min: 4, max: 16, default: 8 },
+    shift: { min: 1, max: 6, default: 3 },
+    sampler: { allowed: ['euler', 'euler_ancestral'], default: 'euler' },
+    scheduler: { allowed: ['simple'], default: 'simple' }
+  },
+  'ace_step_1.5_sft': {
+    steps: { min: 10, max: 100, default: 50 },
+    guidance: { min: 1, max: 15, default: 5 },
+    shift: { min: 1, max: 6, default: 3 },
+    sampler: { allowed: ['euler', 'euler_ancestral', 'er_sde'], default: 'er_sde' },
+    scheduler: { allowed: ['simple', 'linear_quadratic'], default: 'linear_quadratic' }
+  }
+};
+const MUSIC_DURATION_LIMITS = { min: 10, max: 600, default: 30 };
+const MUSIC_BPM_LIMITS = { min: 30, max: 300, default: 120 };
+const MUSIC_PROMPT_STRENGTH_LIMITS = { min: 0, max: 10 };
+const MUSIC_CREATIVITY_LIMITS = { min: 0, max: 2 };
+const MUSIC_OUTPUT_FORMATS = new Set(['mp3', 'flac', 'wav']);
+const MUSIC_TIME_SIGNATURES = new Set(['2', '3', '4', '6']);
 
 function expandHomePath(rawPath) {
   if (typeof rawPath !== 'string') return rawPath;
@@ -96,6 +143,18 @@ function resolveConfiguredPath(rawPath, fallbackPath, label) {
   return sanitizePath(candidate, label);
 }
 
+async function disableLiveModelAvailabilityEvents(wrapper) {
+  const sdkClient = wrapper?.client;
+
+  try {
+    if (typeof sdkClient?.setSocketEventSubscriptions === 'function') {
+      await sdkClient.setSocketEventSubscriptions(SOCKET_EVENT_SUBSCRIPTIONS);
+    }
+  } catch (err) {
+    // Subscription optimization is best-effort and must not block generation.
+  }
+}
+
 function isPathWithinBase(basePath, targetPath) {
   return targetPath === basePath || targetPath.startsWith(`${basePath}${sep}`);
 }
@@ -226,6 +285,9 @@ function applyCreativeBrainPreflight() {
     widthFromPrompt = true;
     heightFromPrompt = true;
   }
+  if (plan.dimensionSource === 'aspect' && plan.aspectRatio && !cliSet.width && !cliSet.height) {
+    aspectRatioFromPrompt = plan.aspectRatio;
+  }
   if (
     Number.isFinite(plan.targetResolution) &&
     !cliSet.targetResolution &&
@@ -250,6 +312,100 @@ function normalizeSeedStrategy(value) {
   return null;
 }
 
+function normalizeApiToolMode(value) {
+  const normalized = String(value || 'creative-agent').toLowerCase();
+  if (normalized === 'creative-agent' || normalized === 'rich') return 'creative-agent';
+  if (normalized === 'hosted' || normalized === 'true') return true;
+  if (normalized === 'none' || normalized === 'false') return false;
+  return null;
+}
+
+function normalizeApiWorkflowKind(value) {
+  const normalized = String(value || '').toLowerCase().replace(/-/g, '_');
+  if (normalized === 'image_to_video' || normalized === 'i2v') return 'image_to_video';
+  if (normalized === 'hosted_tool_sequence' || normalized === 'tool_sequence') return 'hosted_tool_sequence';
+  if (normalized === 'storyboard_video' || normalized === 'storyboard_to_video' || normalized === 'gpt_image_2_seedance' || normalized === 'gpt_image_seedance') {
+    return 'storyboard_video';
+  }
+  return null;
+}
+
+function appendApiPath(baseUrl, path) {
+  const base = String(baseUrl || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+  const suffix = path.startsWith('/') ? path : `/${path}`;
+  return `${base}${suffix}`;
+}
+
+function getApiBaseUrl() {
+  return options.apiBaseUrl || getEnv('SOGNI_API_BASE_URL') || getEnv('SOGNI_REST_ENDPOINT') || DEFAULT_API_BASE_URL;
+}
+
+function getApiAllowedHosts() {
+  const configured = String(getEnv('SOGNI_API_ALLOWED_HOSTS') || '')
+    .split(',')
+    .map((host) => host.trim().toLowerCase())
+    .filter(Boolean);
+  return Array.from(new Set([...DEFAULT_SAFE_API_HOSTS, ...configured]));
+}
+
+function allowUnsafeApiBaseUrl() {
+  return getEnv('SOGNI_ALLOW_UNSAFE_API_BASE_URL') === '1';
+}
+
+function isLoopbackApiUrl(parsed) {
+  return LOOPBACK_API_HOSTS.includes(parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase());
+}
+
+async function buildSafeApiUrl(path) {
+  const url = appendApiPath(getApiBaseUrl(), path);
+  const unsafeAllowed = allowUnsafeApiBaseUrl();
+
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    const err = new Error('Invalid Sogni API base URL.');
+    err.code = 'INVALID_API_BASE_URL';
+    throw err;
+  }
+
+  if (parsed.username || parsed.password) {
+    const err = new Error('Sogni API base URL must not contain credentials.');
+    err.code = 'UNSAFE_API_BASE_URL';
+    throw err;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    const err = new Error(`Sogni API URL protocol ${parsed.protocol} is not allowed.`);
+    err.code = 'UNSAFE_API_BASE_URL';
+    throw err;
+  }
+
+  if (unsafeAllowed) return url;
+
+  if (isLoopbackApiUrl(parsed)) {
+    const err = new Error('Loopback Sogni API base URLs require SOGNI_ALLOW_UNSAFE_API_BASE_URL=1 for isolated local testing.');
+    err.code = 'UNSAFE_API_BASE_URL';
+    throw err;
+  }
+
+  try {
+    await assertSafeUrl(url, {
+      allowedProtocols: ['https:'],
+      allowedHosts: getApiAllowedHosts()
+    });
+  } catch (err) {
+    const wrapped = new Error(
+      `${err.message}. Set SOGNI_API_ALLOWED_HOSTS for a trusted custom API host, or SOGNI_ALLOW_UNSAFE_API_BASE_URL=1 for isolated local testing.`
+    );
+    wrapped.code = 'UNSAFE_API_BASE_URL';
+    wrapped.cause = err;
+    throw wrapped;
+  }
+
+  return url;
+}
+
 function generateRandomSeed() {
   return randomBytes(4).readUInt32BE(0);
 }
@@ -275,7 +431,7 @@ function computePromptHashSeed(opts) {
   const payload = {
     prompt: opts.prompt || '',
     model: opts.model || '',
-    workflow: opts.video ? opts.videoWorkflow : 'image',
+    workflow: opts.video ? opts.videoWorkflow : opts.music ? 'music' : 'image',
     width: opts.width,
     height: opts.height,
     azimuth: opts.azimuth || '',
@@ -285,6 +441,15 @@ function computePromptHashSeed(opts) {
     outputFormat: opts.outputFormat || '',
     sampler: opts.sampler || '',
     scheduler: opts.scheduler || '',
+    musicLyrics: opts.musicLyrics || '',
+    musicLanguage: opts.musicLanguage || '',
+    musicBpm: opts.musicBpm ?? null,
+    musicKeyscale: opts.musicKeyscale || '',
+    musicTimesig: opts.musicTimesig || '',
+    musicComposerMode: opts.musicComposerMode ?? null,
+    musicPromptStrength: opts.musicPromptStrength ?? null,
+    musicCreativity: opts.musicCreativity ?? null,
+    musicShift: opts.musicShift ?? null,
     targetResolution: opts.targetResolution ?? null,
     loras: opts.loras || [],
     loraStrengths: opts.loraStrengths || [],
@@ -338,6 +503,17 @@ function parseNumberList(raw, flagName) {
   return entries.map((entry) => parseNumberValue(entry, flagName));
 }
 
+function parseBoundedNumberValue(raw, flagName, limits) {
+  const num = parseNumberValue(raw, flagName);
+  if (num < limits.min || num > limits.max) {
+    fatalCliError(`${flagName} must be between ${limits.min} and ${limits.max}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw, min: limits.min, max: limits.max }
+    });
+  }
+  return num;
+}
+
 function requireFlagValue(argv, index, flagName) {
   const value = argv[index + 1];
   if (value === undefined) {
@@ -419,17 +595,12 @@ function isHttpUrl(value) {
 }
 
 function isHttpsUrl(value) {
-  return typeof value === 'string' && value.startsWith('https://');
-}
-
-function isSeedanceModelSelection(modelId) {
-  if (!modelId) return false;
-  return (
-    isSeedanceModel(modelId) ||
-    isSeedanceModel(resolveVideoModelAlias(modelId, 't2v')) ||
-    isSeedanceModel(resolveVideoModelAlias(modelId, 'ia2v')) ||
-    isSeedanceModel(resolveVideoModelAlias(modelId, 'v2v'))
-  );
+  if (typeof value !== 'string') return false;
+  try {
+    return new URL(value).protocol === 'https:';
+  } catch {
+    return false;
+  }
 }
 
 function getPngDimensions(buffer) {
@@ -530,6 +701,38 @@ function isWanAnimateVideoModelId(modelId) {
   );
 }
 
+function isGptImage2ModelSelection(modelId) {
+  const normalized = String(modelId || '').trim().toLowerCase();
+  return ['gpt-image-2', 'gptimage2', 'gpt-image', 'gpt_image_2'].includes(normalized);
+}
+
+function normalizeMusicModelId(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  const normalized = raw.toLowerCase().replace(/-/g, '_').replace(/ace_step_1_5/g, 'ace_step_1.5');
+  return MUSIC_MODEL_IDS[normalized] || (MUSIC_MODEL_DEFAULTS[normalized] ? normalized : null);
+}
+
+function getMusicModelDefaults(modelId) {
+  return MUSIC_MODEL_DEFAULTS[normalizeMusicModelId(modelId)] || null;
+}
+
+function normalizeMusicTimeSignature(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  const match = raw.match(/^([2346])(?:\s*\/\s*(?:4|8))?$/);
+  return match ? match[1] : raw;
+}
+
+function requiresSparkOnlyToken(modelId) {
+  return isGptImage2ModelSelection(modelId) || isSeedanceModel(modelId);
+}
+
+function getMaxContextImages(modelId) {
+  if (isGptImage2ModelSelection(modelId)) return 16;
+  return getWrapperMaxContextImages(modelId);
+}
+
 function videoDurationLimitsLikeWrapper(modelId) {
   if (isSeedanceModel(modelId)) return { min: 4, max: 15 };
   if (isLtx2Model(modelId) || isWanAnimateVideoModelId(modelId)) return { min: 1, max: 20 };
@@ -800,7 +1003,7 @@ const openclawConfig = loadOpenClawPluginConfig();
 const CREDENTIALS_PATH = resolveConfiguredPath(
   getEnv('SOGNI_CREDENTIALS_PATH') || openclawConfig?.credentialsPath,
   DEFAULT_CREDENTIALS_PATH,
-  'SOGNI credentials path'
+  'SOGNI API key credentials path'
 );
 const LAST_RENDER_PATH = resolveConfiguredPath(
   getEnv('SOGNI_LAST_RENDER_PATH') || openclawConfig?.lastRenderPath,
@@ -845,6 +1048,16 @@ const options = {
   seed: null,
   lastSeed: false,
   seedStrategy: null,
+  music: false,
+  musicLyrics: null,
+  musicLanguage: null,
+  musicBpm: null,
+  musicKeyscale: null,
+  musicTimesig: null,
+  musicComposerMode: null,
+  musicPromptStrength: null,
+  musicCreativity: null,
+  musicShift: null,
   video: false,
   videoWorkflow: null,
   fps: 16,
@@ -898,6 +1111,24 @@ const options = {
   personaVoice: null,
   personaVoiceClip: null,
   personaPhoto: null, // alias for --ref when used with --persona-add
+  apiChat: false,
+  apiBaseUrl: null,
+  llmModel: DEFAULT_LLM_MODEL,
+  apiTools: 'creative-agent',
+  apiToolExecution: true,
+  apiSystemPrompt: null,
+  apiWorkflowAction: null, // start|list|get|events|stream|cancel
+  apiWorkflowKind: null, // image_to_video|hosted_tool_sequence
+  apiWorkflowInput: null,
+  apiWorkflowTitle: null,
+  apiWorkflowIdempotencyKey: null,
+  apiWorkflowId: null,
+  apiWorkflowWatch: false,
+  apiVideoPrompt: null,
+  apiNegativePrompt: null,
+  apiGenerateAudio: null,
+  apiExpandPrompt: null,
+  storyboardFrames: null,
   noFilter: false // Disable NSFW content filter
 };
 const cliSet = {
@@ -925,6 +1156,16 @@ const cliSet = {
   angleDescription: false,
   seed: false,
   seedStrategy: false,
+  music: false,
+  musicLyrics: false,
+  musicLanguage: false,
+  musicBpm: false,
+  musicKeyscale: false,
+  musicTimesig: false,
+  musicComposerMode: false,
+  musicPromptStrength: false,
+  musicCreativity: false,
+  musicShift: false,
   video: false,
   workflow: false,
   fps: false,
@@ -953,7 +1194,20 @@ const cliSet = {
   sam2Coordinates: false,
   trimEndFrame: false,
   firstFrameStrength: false,
-  lastFrameStrength: false
+  lastFrameStrength: false,
+  apiBaseUrl: false,
+  llmModel: false,
+  apiTools: false,
+  apiSystemPrompt: false,
+  apiWorkflowKind: false,
+  apiWorkflowInput: false,
+  apiWorkflowTitle: false,
+  apiWorkflowIdempotencyKey: false,
+  apiVideoPrompt: false,
+  apiNegativePrompt: false,
+  apiGenerateAudio: false,
+  apiExpandPrompt: false,
+  storyboardFrames: false
 };
 
 // Parse CLI args
@@ -1099,6 +1353,70 @@ for (let i = 0; i < args.length; i++) {
     cliSet.seedStrategy = true;
   } else if (arg === '--last-seed' || arg === '--reseed') {
     options.lastSeed = true;
+  } else if (arg === '--music' || arg === '--generate-music') {
+    options.music = true;
+    cliSet.music = true;
+  } else if (arg === '--music-model' || arg === '--audio-model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.model = raw;
+    cliSet.model = true;
+  } else if (arg === '--lyrics') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicLyrics = raw;
+    cliSet.musicLyrics = true;
+  } else if (arg === '--language' || arg === '--lyrics-language') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicLanguage = raw;
+    cliSet.musicLanguage = true;
+  } else if (arg === '--bpm') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicBpm = parseBoundedNumberValue(raw, arg, MUSIC_BPM_LIMITS);
+    cliSet.musicBpm = true;
+  } else if (arg === '--keyscale' || arg === '--key-scale' || arg === '--key') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicKeyscale = raw;
+    cliSet.musicKeyscale = true;
+  } else if (arg === '--timesig' || arg === '--time-signature') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicTimesig = normalizeMusicTimeSignature(raw);
+    cliSet.musicTimesig = true;
+  } else if (arg === '--composer-mode') {
+    options.musicComposerMode = true;
+    cliSet.musicComposerMode = true;
+  } else if (arg === '--no-composer-mode') {
+    options.musicComposerMode = false;
+    cliSet.musicComposerMode = true;
+  } else if (arg === '--prompt-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicPromptStrength = parseBoundedNumberValue(raw, arg, MUSIC_PROMPT_STRENGTH_LIMITS);
+    cliSet.musicPromptStrength = true;
+  } else if (arg === '--creativity') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicCreativity = parseBoundedNumberValue(raw, arg, MUSIC_CREATIVITY_LIMITS);
+    cliSet.musicCreativity = true;
+  } else if (arg === '--music-shift' || arg === '--audio-shift') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.musicShift = parseNumberValue(raw, arg);
+    cliSet.musicShift = true;
+  } else if (arg === '--audio-format') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.outputFormat = raw;
+    cliSet.outputFormat = true;
+  } else if (arg === '--length') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.duration = parsePositiveIntegerValue(raw, arg);
+    cliSet.duration = true;
   } else if (arg === '--video' || arg === '-v') {
     options.video = true;
     cliSet.video = true;
@@ -1278,6 +1596,103 @@ for (let i = 0; i < args.length; i++) {
     } else {
       options.listMedia = 'images';
     }
+  // --- Hosted Sogni API paths ---
+  } else if (arg === '--api-chat') {
+    options.apiChat = true;
+  } else if (arg === '--api-base-url' || arg === '--api-base') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiBaseUrl = raw;
+    cliSet.apiBaseUrl = true;
+  } else if (arg === '--llm-model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.llmModel = raw;
+    cliSet.llmModel = true;
+  } else if (arg === '--api-tools') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiTools = raw;
+    cliSet.apiTools = true;
+  } else if (arg === '--no-api-tool-execution') {
+    options.apiToolExecution = false;
+  } else if (arg === '--system') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiSystemPrompt = raw;
+    cliSet.apiSystemPrompt = true;
+  } else if (arg === '--api-workflow' || arg === '--creative-workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'start';
+    options.apiWorkflowKind = raw;
+    cliSet.apiWorkflowKind = true;
+  } else if (arg === '--workflow-input') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowInput = raw;
+    cliSet.apiWorkflowInput = true;
+  } else if (arg === '--workflow-title') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowTitle = raw;
+    cliSet.apiWorkflowTitle = true;
+  } else if (arg === '--workflow-idempotency-key' || arg === '--idempotency-key') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowIdempotencyKey = raw;
+    cliSet.apiWorkflowIdempotencyKey = true;
+  } else if (arg === '--storyboard-frames') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.storyboardFrames = parsePositiveIntegerValue(raw, arg);
+    cliSet.storyboardFrames = true;
+  } else if (arg === '--video-prompt') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiVideoPrompt = raw;
+    cliSet.apiVideoPrompt = true;
+  } else if (arg === '--negative-prompt') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiNegativePrompt = raw;
+    cliSet.apiNegativePrompt = true;
+  } else if (arg === '--generate-audio') {
+    options.apiGenerateAudio = true;
+    cliSet.apiGenerateAudio = true;
+  } else if (arg === '--no-generate-audio') {
+    options.apiGenerateAudio = false;
+    cliSet.apiGenerateAudio = true;
+  } else if (arg === '--expand-prompt') {
+    options.apiExpandPrompt = true;
+    cliSet.apiExpandPrompt = true;
+  } else if (arg === '--no-expand-prompt') {
+    options.apiExpandPrompt = false;
+    cliSet.apiExpandPrompt = true;
+  } else if (arg === '--watch-workflow' || arg === '--watch') {
+    options.apiWorkflowWatch = true;
+  } else if (arg === '--list-workflows') {
+    options.apiWorkflowAction = 'list';
+  } else if (arg === '--get-workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'get';
+    options.apiWorkflowId = raw;
+  } else if (arg === '--workflow-events') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'events';
+    options.apiWorkflowId = raw;
+  } else if (arg === '--stream-workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'stream';
+    options.apiWorkflowId = raw;
+  } else if (arg === '--cancel-workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'cancel';
+    options.apiWorkflowId = raw;
   // --- Memory commands ---
   } else if (arg === '--memory-set') {
     options.memoryAction = 'set';
@@ -1368,7 +1783,7 @@ for (let i = 0; i < args.length; i++) {
     options.showVersion = true;
   } else if (arg === '--help') {
     console.log(`
-sogni-agent - Generate images and videos using Sogni AI
+sogni-agent - Generate images, videos, and music using Sogni AI
 
 Usage: sogni-agent [options] "prompt"
 
@@ -1378,7 +1793,7 @@ Image Options:
   -m, --model <id>      Model (default: z_image_turbo_bf16, overrides --quality)
   -w, --width <px>      Width (default: 512)
   -h, --height <px>     Height (default: 512)
-  -n, --count <num>     Number of images (default: 1)
+  -n, --count <num>     Number of outputs (default: 1)
   -s, --seed <num>      Use specific seed
   --last-seed           Reuse seed from previous render
   --seed-strategy <s>   Seed strategy: random|prompt-hash
@@ -1391,7 +1806,7 @@ Image Options:
   --distance <key>      close-up|medium|wide
   --angle-strength <n>  LoRA strength for multiple_angles (default: 0.9)
   --angle-description <text>  Optional subject description
-  --output-format <f>   Image output format: png|jpg
+  --output-format <f>   Image output format: png|jpg (webp for gpt-image-2)
   --sampler <name>      Sampler (model-dependent)
   --scheduler <name>    Scheduler (model-dependent)
   --lora <id>           LoRA id (repeatable, edit only)
@@ -1407,6 +1822,23 @@ Photobooth (Face Transfer):
   --cn-strength <n>       ControlNet strength (default: 0.8)
   --cn-guidance-end <n>   ControlNet guidance end point (default: 0.3)
 
+Music Options:
+  --music               Generate music/audio instead of image
+  --music-model <id>    Music model: turbo|sft|ace_step_1.5_turbo|ace_step_1.5_sft
+  --lyrics <text>       Optional song lyrics (omit for instrumental)
+  --language <code>     Lyrics language code (default: en)
+  --duration <sec>      Music duration in seconds (10-600, default: 30)
+  --length <sec>        Alias for --duration
+  --bpm <num>           Beats per minute (30-300)
+  --keyscale <text>     Key/scale, e.g. "C major" or "A minor"
+  --timesig <n>         Time signature: 2|3|4|6 (also accepts 4/4)
+  --composer-mode       Enable AI composer mode
+  --no-composer-mode    Disable AI composer mode
+  --prompt-strength <n> Prompt adherence (0-10)
+  --creativity <n>      Composition variation/temperature (0-2)
+  --music-shift <n>     Audio model shift parameter (1-6)
+  --audio-format <f>    Alias for --output-format: mp3|flac|wav
+
 Video Options:
   --video, -v           Generate video instead of image
   --workflow <type>     Video workflow: t2v|i2v|s2v|ia2v|a2v|v2v|animate-move|animate-replace
@@ -1435,8 +1867,31 @@ Video Options:
   --looping, --loop     Create seamless loop (i2v only): A→B→A
   --last-image          Use last generated image as reference
 
+Hosted API Modes:
+  --api-chat            Use /v1/chat/completions with rich creative-agent tools
+  --api-tools <mode>    creative-agent|rich|hosted|none (default: creative-agent)
+  --no-api-tool-execution  Ask for tool calls/plans but do not execute Sogni tools
+  --llm-model <id>      LLM model for --api-chat (default: ${DEFAULT_LLM_MODEL})
+  --system <text>       System prompt for --api-chat
+  --api-workflow <kind> Start /v1/creative-agent/workflows: image-to-video|hosted-tool-sequence|storyboard-video
+  --workflow-input <json|path|@path> JSON input for hosted-tool-sequence/custom image-to-video/storyboard-video
+  --workflow-title <text> Title for hosted-tool-sequence or storyboard-video workflow input
+  --workflow-idempotency-key <key> Reuse safely when retrying a workflow start request
+  --storyboard-frames <n> Frame/beat count for --api-workflow storyboard-video
+  --video-prompt <text> Motion prompt for --api-workflow image-to-video
+  --negative-prompt <text> Negative prompt for --api-workflow image-to-video
+  --generate-audio, --no-generate-audio  Toggle audio generation for image-to-video workflows
+  --expand-prompt, --no-expand-prompt    Toggle prompt expansion for image-to-video workflows
+  --watch-workflow      Stream workflow events after starting
+  --list-workflows      List recent durable creative workflows
+  --get-workflow <id>   Fetch a workflow snapshot
+  --workflow-events <id> Fetch workflow event history
+  --stream-workflow <id> Stream workflow events over SSE
+  --cancel-workflow <id> Cancel a running workflow
+  --api-base-url <url>  Sogni API base URL (default: ${DEFAULT_API_BASE_URL})
+
 General:
-  -t, --timeout <sec>   Timeout in seconds (default: 30, video: 300)
+  -t, --timeout <sec>   Timeout in seconds (default: 30, video: 300, music: 600)
   --steps <num>         Override steps (model-dependent)
   --guidance <num>      Override guidance (model-dependent)
   --token-type <type>   Token type: spark|sogni|auto (default: spark, auto retries with alternate)
@@ -1479,6 +1934,7 @@ Personas (named people with reference photos):
 
 Image Models:
   z_image_turbo_bf16              Fast, general purpose (default)
+  gpt-image-2                     OpenAI GPT Image 2 text-to-image and edit (up to 16 context images)
   flux1-schnell-fp8               Very fast
   flux2_dev_fp8                   High quality (slow)
   qwen_image_edit_2511_fp8        Image editing with context (up to 3 images)
@@ -1491,7 +1947,11 @@ Recommended LTX 2.3 Video Models:
   ltx23-22b-fp8_a2v_distilled     Audio-to-video
   ltx23-22b-fp8_v2v_distilled     Video-to-video with ControlNet
 
-Seedance 2.0 Video Aliases:
+Music Models:
+  ace_step_1.5_turbo              Default direct music generation
+  ace_step_1.5_sft                Experimental model with stronger lyric handling
+
+Seedance 2.0 Video Model Selectors:
   seedance2                         Text-to-video, 4-15s, native audio, HTTPS multimodal refs
   seedance2-fast                    Fast 720p-capped text-to-video
   seedance2-ia2v                    Image+audio-to-video
@@ -1522,11 +1982,16 @@ Examples:
   sogni-agent --multi-angle -c subject.jpg --azimuth front-right --elevation eye-level --distance medium "studio portrait"
   sogni-agent --angles-360 -c subject.jpg "studio portrait"
   sogni-agent --video --ref cat.jpg -o cat.mp4 "cat walks around"
-  sogni-agent --video "A narrator says \"welcome to the story\" as ocean waves crash"
+  sogni-agent --video 'A narrator says "welcome to the story" as ocean waves crash'
   sogni-agent --video --ref cat.jpg --ref-audio speech.m4a -m wan_v2.2-14b-fp8_s2v_lightx2v "lip sync"
   sogni-agent --video --ref cover.jpg --ref-audio song.mp3 "music video"
   sogni-agent --video --ref-audio song.mp3 "abstract music visualizer"
-  sogni-agent --video --reference-audio-identity voice.webm "NARRATOR: \"This is my voice.\""
+  sogni-agent --music --duration 30 "uplifting cinematic synthwave theme for a product launch"
+  sogni-agent --music --lyrics "Rise with the morning light" --bpm 128 --keyscale "C major" --output-format mp3 "bright indie pop chorus"
+  sogni-agent --video --reference-audio-identity voice.webm 'NARRATOR: "This is my voice."'
+  sogni-agent --api-chat "Create a 4-shot product video concept for a red sneaker"
+  sogni-agent --api-workflow image-to-video --video-prompt "slow push-in as it comes alive" "a graphite robot sketch"
+  sogni-agent --api-workflow storyboard-video --storyboard-frames 6 "Create a 12s 9:16 bakery launch video with GPT Image 2 and Seedance"
   sogni-agent --video -m ltx23-22b-fp8_t2v_distilled --duration 20 "A wide cinematic aerial shot opens over steep tropical cliffs at golden hour, warm sunlight grazing the rock faces while sea mist drifts above the water below. Palm trees bend gently along the ridge as waves roll against the shoreline, leaving bright bands of foam across the dark stone. The camera glides forward in one continuous pass, revealing more of the coastline as sunlight flickers across wet surfaces and distant birds wheel through the haze. The scene holds a calm, upscale travel-film mood with smooth stabilized motion and crisp environmental detail."
   sogni-agent --video --ref subject.jpg --ref-video motion.mp4 --workflow animate-move "transfer motion"
   sogni-agent --video --last-image "gentle camera pan"
@@ -1561,6 +2026,7 @@ let widthFromPrompt = false;
 let heightFromPrompt = false;
 let targetResolutionFromPrompt = false;
 let durationFromPrompt = false;
+let aspectRatioFromPrompt = null;
 let configuredDefaultVideoWorkflow = null;
 if (openclawConfig) {
   const isNumber = (value) => Number.isFinite(value);
@@ -1578,10 +2044,27 @@ if (openclawConfig) {
   if (!cliSet.tokenType && openclawConfig.defaultTokenType) {
     options.tokenType = openclawConfig.defaultTokenType;
   }
+  if (!cliSet.apiBaseUrl && openclawConfig.apiBaseUrl) {
+    options.apiBaseUrl = openclawConfig.apiBaseUrl;
+  }
+  if (!cliSet.llmModel && openclawConfig.defaultLlmModel) {
+    options.llmModel = openclawConfig.defaultLlmModel;
+  }
+  if (!cliSet.apiTools && openclawConfig.defaultApiToolMode) {
+    options.apiTools = openclawConfig.defaultApiToolMode;
+  }
   if (!cliSet.seedStrategy && openclawConfig.seedStrategy) {
     options.seedStrategy = openclawConfig.seedStrategy;
   }
-  if (options.video) {
+  if (options.music) {
+    if (!cliSet.duration && isNumber(openclawConfig.defaultMusicDurationSec)) {
+      options.duration = openclawConfig.defaultMusicDurationSec;
+    }
+    if (!cliSet.timeout && isNumber(openclawConfig.defaultMusicTimeoutSec)) {
+      options.timeout = openclawConfig.defaultMusicTimeoutSec * 1000;
+      timeoutFromConfig = true;
+    }
+  } else if (options.video) {
     if (!cliSet.workflow && openclawConfig.defaultVideoWorkflow) {
       configuredDefaultVideoWorkflow = openclawConfig.defaultVideoWorkflow;
     }
@@ -1613,6 +2096,26 @@ if (options.tokenType) {
   options.tokenType = token;
 }
 
+const normalizedApiToolMode = normalizeApiToolMode(options.apiTools);
+if (normalizedApiToolMode === null) {
+  fatalCliError('--api-tools must be "creative-agent", "rich", "hosted", or "none".', {
+    code: 'INVALID_ARGUMENT',
+    details: { flag: '--api-tools', value: options.apiTools }
+  });
+}
+options.apiTools = normalizedApiToolMode;
+
+if (options.apiWorkflowKind) {
+  const normalized = normalizeApiWorkflowKind(options.apiWorkflowKind);
+  if (!normalized) {
+    fatalCliError('--api-workflow must be "image-to-video", "hosted-tool-sequence", or "storyboard-video".', {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: '--api-workflow', value: options.apiWorkflowKind }
+    });
+  }
+  options.apiWorkflowKind = normalized;
+}
+
 if (options.quality) {
   if (!QUALITY_TIERS[options.quality]) {
     fatalCliError('--quality must be "fast", "hq", or "pro".', {
@@ -1620,8 +2123,13 @@ if (options.quality) {
       details: { flag: '--quality', value: options.quality }
     });
   }
+  if (options.music) {
+    fatalCliError('--quality is not used for --music. Use --music-model turbo|sft for music model selection.', {
+      code: 'INVALID_ARGUMENT'
+    });
+  }
   const tier = QUALITY_TIERS[options.quality];
-  if (!options.video) {
+  if (!options.video && !options.music) {
     // Only apply model if user didn't explicitly set one.
     if (!cliSet.model) {
       options.model = tier.model;
@@ -1663,6 +2171,26 @@ if (cliSet.guidance && !Number.isFinite(options.guidance)) {
   });
 }
 
+if (options.music && options.video) {
+  fatalCliError('--music cannot be combined with --video.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (options.music && (
+  cliSet.width ||
+  cliSet.height ||
+  options.strictSize ||
+  options.multiAngle ||
+  options.angles360Video ||
+  options.photobooth ||
+  options.contextImages.length > 0 ||
+  options.refImage ||
+  options.refImageEnd
+)) {
+  fatalCliError('--music cannot be combined with image/video reference or sizing options.', {
+    code: 'INVALID_ARGUMENT'
+  });
+}
+
 if (options.multiAngle) {
   if (options.video) {
     fatalCliError('--multi-angle is only for image editing.', { code: 'INVALID_ARGUMENT' });
@@ -1758,15 +2286,22 @@ if (options.multiAngle) {
 if (options.outputFormat) {
   const normalized = options.outputFormat.toLowerCase();
   options.outputFormat = normalized === 'jpeg' ? 'jpg' : normalized;
-  if (options.video) {
+  if (options.music) {
+    if (!MUSIC_OUTPUT_FORMATS.has(options.outputFormat)) {
+      fatalCliError('Music output format must be "mp3", "flac", or "wav".', {
+        code: 'INVALID_ARGUMENT',
+        details: { outputFormat: options.outputFormat }
+      });
+    }
+  } else if (options.video) {
     if (options.outputFormat !== 'mp4') {
       fatalCliError('Video output format must be "mp4".', {
         code: 'INVALID_ARGUMENT',
         details: { outputFormat: options.outputFormat }
       });
     }
-  } else if (!['png', 'jpg'].includes(options.outputFormat)) {
-    fatalCliError('Image output format must be "png" or "jpg".', {
+  } else if (!['png', 'jpg', ...(isGptImage2ModelSelection(options.model) ? ['webp'] : [])].includes(options.outputFormat)) {
+    fatalCliError(isGptImage2ModelSelection(options.model) ? 'GPT Image 2 output format must be "png", "jpg", or "webp".' : 'Image output format must be "png" or "jpg".', {
       code: 'INVALID_ARGUMENT',
       details: { outputFormat: options.outputFormat }
     });
@@ -1785,7 +2320,7 @@ if (options.loraStrengths.length > 0 && options.loras.length > 0 &&
   });
 }
 
-if (options.video && options.loras.length > 0) {
+if ((options.video || options.music) && options.loras.length > 0) {
   fatalCliError('--lora options are image-only.', { code: 'INVALID_ARGUMENT' });
 }
 
@@ -1820,6 +2355,15 @@ if (options.video) {
     options.videoWorkflow = normalized;
   }
 
+  if (
+    options._lastImagePath &&
+    !options.refImage &&
+    (!options.videoWorkflow || workflowRequiresImage(options.videoWorkflow) || isSeedanceModelSelection(options.model))
+  ) {
+    options.refImage = options._lastImagePath;
+    delete options._lastImagePath;
+  }
+
   applyCreativeBrainPreflight();
 
   if (!options.videoWorkflow && isSeedanceModelSelection(options.model)) {
@@ -1864,7 +2408,41 @@ if (options._lastImagePath) {
 }
 
 // Set defaults based on type and context
-if (options.video) {
+if (options.music) {
+  const configuredMusicModel = options.model || openclawConfig?.defaultMusicModel || 'turbo';
+  options.model = normalizeMusicModelId(configuredMusicModel);
+  if (!options.model) {
+    fatalCliError(`Unknown music model "${configuredMusicModel}". Use turbo, sft, ace_step_1.5_turbo, or ace_step_1.5_sft.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: cliSet.model ? '--model' : 'defaultMusicModel', value: configuredMusicModel }
+    });
+  }
+  const musicDefaults = getMusicModelDefaults(options.model);
+  if (!cliSet.duration || !Number.isFinite(options.duration)) {
+    options.duration = MUSIC_DURATION_LIMITS.default;
+  }
+  if (!options.outputFormat) {
+    options.outputFormat = 'mp3';
+  }
+  if (!cliSet.steps) {
+    options.steps = musicDefaults.steps.default;
+  }
+  if (!cliSet.guidance && musicDefaults.guidance) {
+    options.guidance = musicDefaults.guidance.default;
+  }
+  if (!cliSet.sampler) {
+    options.sampler = musicDefaults.sampler.default;
+  }
+  if (!cliSet.scheduler) {
+    options.scheduler = musicDefaults.scheduler.default;
+  }
+  if (!cliSet.musicShift) {
+    options.musicShift = musicDefaults.shift.default;
+  }
+  if (!cliSet.timeout && !timeoutFromConfig && options.timeout === 30000) {
+    options.timeout = 600000;
+  }
+} else if (options.video) {
   options.model = options.model || selectDefaultVideoModel(options.videoWorkflow, options, openclawConfig) || 'wan_v2.2-14b-fp8_i2v_lightx2v';
   options.model = resolveVideoModelAlias(options.model, options.videoWorkflow);
   const videoModelDefaults = getModelDefaults(options.model, openclawConfig);
@@ -1892,6 +2470,15 @@ if (options.video) {
     options.width = dims.width;
     options.height = dims.height;
   }
+  if (aspectRatioFromPrompt && !cliSet.width && !cliSet.height) {
+    const dims = dimensionsForAspectRatio(options.width, options.height, aspectRatioFromPrompt);
+    if (dims) {
+      options.width = dims.width;
+      options.height = dims.height;
+      widthFromPrompt = true;
+      heightFromPrompt = true;
+    }
+  }
   if (!cliSet.timeout && !timeoutFromConfig && options.timeout === 30000) {
     options.timeout = 300000; // 5 min for video
   }
@@ -1913,11 +2500,130 @@ if (options.video) {
   options.model = options.model || openclawConfig?.defaultImageModel || 'z_image_turbo_bf16';
 }
 
-if (!options.prompt && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !(options.personaAction && options.personaAction !== 'generate')) {
+if (options.music) {
+  const musicDefaults = getMusicModelDefaults(options.model);
+  if (options.duration < MUSIC_DURATION_LIMITS.min || options.duration > MUSIC_DURATION_LIMITS.max) {
+    fatalCliError(`Music duration must be between ${MUSIC_DURATION_LIMITS.min} and ${MUSIC_DURATION_LIMITS.max} seconds.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { duration: options.duration }
+    });
+  }
+  if (options.musicBpm !== null && options.musicBpm !== undefined) {
+    if (options.musicBpm < MUSIC_BPM_LIMITS.min || options.musicBpm > MUSIC_BPM_LIMITS.max) {
+      fatalCliError(`Music BPM must be between ${MUSIC_BPM_LIMITS.min} and ${MUSIC_BPM_LIMITS.max}.`, {
+        code: 'INVALID_ARGUMENT',
+        details: { bpm: options.musicBpm }
+      });
+    }
+  }
+  if (options.musicTimesig && !MUSIC_TIME_SIGNATURES.has(options.musicTimesig)) {
+    fatalCliError('--timesig must be one of 2, 3, 4, or 6.', {
+      code: 'INVALID_ARGUMENT',
+      details: { timesig: options.musicTimesig }
+    });
+  }
+  if (options.steps !== null && options.steps !== undefined) {
+    const { min, max } = musicDefaults.steps;
+    if (!Number.isFinite(options.steps) || options.steps < min || options.steps > max) {
+      fatalCliError(`--steps for ${options.model} must be between ${min} and ${max}.`, {
+        code: 'INVALID_ARGUMENT',
+        details: { model: options.model, steps: options.steps, min, max }
+      });
+    }
+  }
+  if (options.guidance !== null && options.guidance !== undefined && musicDefaults.guidance) {
+    const { min, max } = musicDefaults.guidance;
+    if (!Number.isFinite(options.guidance) || options.guidance < min || options.guidance > max) {
+      fatalCliError(`--guidance for ${options.model} must be between ${min} and ${max}.`, {
+        code: 'INVALID_ARGUMENT',
+        details: { model: options.model, guidance: options.guidance, min, max }
+      });
+    }
+  }
+  if (options.musicShift !== null && options.musicShift !== undefined) {
+    const { min, max } = musicDefaults.shift;
+    if (!Number.isFinite(options.musicShift) || options.musicShift < min || options.musicShift > max) {
+      fatalCliError(`--music-shift for ${options.model} must be between ${min} and ${max}.`, {
+        code: 'INVALID_ARGUMENT',
+        details: { model: options.model, shift: options.musicShift, min, max }
+      });
+    }
+  }
+  if (options.sampler && !musicDefaults.sampler.allowed.includes(options.sampler)) {
+    fatalCliError(`--sampler for ${options.model} must be one of ${musicDefaults.sampler.allowed.join('|')}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { model: options.model, sampler: options.sampler, allowed: musicDefaults.sampler.allowed }
+    });
+  }
+  if (options.scheduler && !musicDefaults.scheduler.allowed.includes(options.scheduler)) {
+    fatalCliError(`--scheduler for ${options.model} must be one of ${musicDefaults.scheduler.allowed.join('|')}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { model: options.model, scheduler: options.scheduler, allowed: musicDefaults.scheduler.allowed }
+    });
+  }
+}
+
+const apiWorkflowUtilityAction = options.apiWorkflowAction && options.apiWorkflowAction !== 'start';
+const apiWorkflowStartAction = options.apiWorkflowAction === 'start';
+const apiWorkflowStartHasExternalInput = options.apiWorkflowAction === 'start' && options.apiWorkflowInput;
+const personaUtilityAction = Boolean(options.personaAction && options.personaAction !== 'generate');
+const commandUsesGenerationSeed = !options.apiChat &&
+  !apiWorkflowUtilityAction &&
+  !options.estimateVideoCost &&
+  !options.showBalance &&
+  !options.showVersion &&
+  !options.extractLastFrame &&
+  !options.concatVideos &&
+  !options.listMedia &&
+  !options.memoryAction &&
+  !options.personalityAction &&
+  !personaUtilityAction;
+if (apiWorkflowStartAction && options.apiWorkflowKind === 'image_to_video' && !options.prompt && !apiWorkflowStartHasExternalInput) {
+  fatalCliError('--api-workflow image-to-video requires a prompt or --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
+}
+if (apiWorkflowStartAction && options.apiWorkflowKind === 'hosted_tool_sequence' && !apiWorkflowStartHasExternalInput) {
+  fatalCliError('--api-workflow hosted-tool-sequence requires --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
+}
+if (apiWorkflowStartAction && options.apiWorkflowKind === 'storyboard_video' && !options.prompt && !apiWorkflowStartHasExternalInput) {
+  fatalCliError('--api-workflow storyboard-video requires a prompt or --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
+}
+if (!options.prompt && !options.apiChat && !apiWorkflowUtilityAction && !apiWorkflowStartAction && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !personaUtilityAction) {
   fatalCliError('No prompt provided. Use --help for usage.', { code: 'INVALID_ARGUMENT' });
 }
 
-if (!options.video && (options.refAudio || options.refVideo || options.referenceAudioIdentity || options.voicePersonaName || options.videoWorkflow || options.frames || options.targetResolution || options.audioStart !== null || options.audioDuration !== null || options.videoStart !== null)) {
+if (options.apiChat && !options.prompt && options.contextImages.length === 0 && !options.refImage && !options.refImageEnd) {
+  fatalCliError('--api-chat requires a prompt or an image reference for vision-only planning.', { code: 'INVALID_ARGUMENT' });
+}
+
+const apiMediaRefs = getApiModeMediaReferences();
+const apiImageRefs = apiMediaRefs.filter(ref => ref.kind === 'image');
+const apiNonImageRefs = apiMediaRefs.filter(ref => ref.kind !== 'image');
+if (options.apiChat && apiNonImageRefs.length > 0) {
+  fatalCliError(
+    `--api-chat does not support ${formatApiMediaFlags(apiNonImageRefs)}. Use the direct CLI path for audio/video media workflows.`,
+    { code: 'UNSUPPORTED_API_MEDIA_REFERENCE' }
+  );
+}
+if (options.apiChat && options.apiToolExecution && apiImageRefs.length > 0) {
+  fatalCliError(
+    '--api-chat with server-side tool execution does not currently support image references. Use the direct CLI path for uploaded-media workflows, or pass --no-api-tool-execution for vision-only chat/planning.',
+    { code: 'UNSUPPORTED_API_UPLOAD_EXECUTION' }
+  );
+}
+if (options.apiWorkflowAction && apiMediaRefs.length > 0) {
+  fatalCliError(
+    `Hosted workflow API modes do not accept CLI media reference flags (${formatApiMediaFlags(apiMediaRefs)}). Use --workflow-input JSON for hosted workflow inputs, or use the direct CLI path for local media workflows.`,
+    { code: 'UNSUPPORTED_API_MEDIA_REFERENCE' }
+  );
+}
+if (options.apiWorkflowAction === 'start' && options.apiWorkflowKind === 'image_to_video' && options.apiWorkflowTitle) {
+  fatalCliError('--workflow-title is currently only supported with --api-workflow hosted-tool-sequence or storyboard-video.', {
+    code: 'INVALID_ARGUMENT',
+    details: { flag: '--workflow-title', workflow: options.apiWorkflowKind }
+  });
+}
+
+if (!options.video && !options.apiChat && !options.apiWorkflowAction && (options.refAudio || options.refVideo || options.referenceAudioIdentity || options.voicePersonaName || options.videoWorkflow || options.frames || options.targetResolution || options.audioStart !== null || options.audioDuration !== null || options.videoStart !== null)) {
   fatalCliError('Video-only options (--workflow/--frames/--target-resolution/--ref-audio/--ref-video/--reference-audio-identity/--voice-persona) require --video.', {
     code: 'INVALID_ARGUMENT'
   });
@@ -2246,8 +2952,8 @@ if (options.contextImages.length > 0 && !options.video) {
   }
 }
 
-// Load last render seed if requested
-if (options.lastSeed) {
+// Load last render seed if requested for a command that can use it.
+if (options.lastSeed && commandUsesGenerationSeed) {
   if (existsSync(LAST_RENDER_PATH)) {
     try {
       const lastRender = JSON.parse(readFileSync(LAST_RENDER_PATH, 'utf8'));
@@ -2263,7 +2969,7 @@ if (options.lastSeed) {
   }
 }
 
-if (!options.estimateVideoCost && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && (options.seed === null || options.seed === undefined)) {
+if (commandUsesGenerationSeed && (options.seed === null || options.seed === undefined)) {
   const strategy = options.seedStrategy || openclawConfig?.seedStrategy || 'prompt-hash';
   const normalized = normalizeSeedStrategy(strategy) || 'prompt-hash';
   options.seedStrategy = normalized;
@@ -2287,9 +2993,6 @@ function loadCredentials() {
         SOGNI_API_KEY: creds.SOGNI_API_KEY
       };
     }
-    if (creds.SOGNI_USERNAME && creds.SOGNI_PASSWORD) {
-      return creds;
-    }
   }
 
   if (hasEnv('SOGNI_API_KEY')) {
@@ -2297,19 +3000,12 @@ function loadCredentials() {
       SOGNI_API_KEY: getEnv('SOGNI_API_KEY')
     };
   }
-  
-  if (hasEnv('SOGNI_USERNAME') && hasEnv('SOGNI_PASSWORD')) {
-    return {
-      SOGNI_USERNAME: getEnv('SOGNI_USERNAME'),
-      SOGNI_PASSWORD: getEnv('SOGNI_PASSWORD')
-    };
-  }
 
-  const err = new Error('No Sogni credentials found.');
+  const err = new Error('No Sogni API key found.');
   err.code = 'MISSING_CREDENTIALS';
-  err.hint = 'Set SOGNI_API_KEY or SOGNI_USERNAME/SOGNI_PASSWORD, or configure SOGNI_CREDENTIALS_PATH.';
+  err.hint = 'Set SOGNI_API_KEY, or configure SOGNI_CREDENTIALS_PATH with SOGNI_API_KEY. You can find your API key by logging into https://dashboard.sogni.ai and clicking your username.';
   err.details = {
-    triedEnv: ['SOGNI_API_KEY', 'SOGNI_USERNAME', 'SOGNI_PASSWORD'],
+    triedEnv: ['SOGNI_API_KEY'],
     triedFile: CREDENTIALS_PATH
   };
   throw err;
@@ -2326,20 +3022,637 @@ function saveLastRender(info) {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Memory system — persistent user preferences on disk
-// ---------------------------------------------------------------------------
-const MEMORIES_PATH = getEnv('SOGNI_MEMORIES_PATH') || DEFAULT_MEMORIES_PATH;
+function requireApiKeyCredentials(creds, modeLabel) {
+  if (creds?.SOGNI_API_KEY) return creds.SOGNI_API_KEY;
+  const err = new Error(`${modeLabel} requires SOGNI_API_KEY API-key authentication.`);
+  err.code = 'MISSING_API_KEY';
+  err.hint = 'Create an API key and set SOGNI_API_KEY; username/password auth is only supported by the direct client-wrapper path.';
+  throw err;
+}
 
-function loadMemories() {
-  try {
-    if (existsSync(MEMORIES_PATH)) return JSON.parse(readFileSync(MEMORIES_PATH, 'utf8'));
-  } catch {}
-  return [];
+function apiRequestHeaders(apiKey, extra = {}) {
+  return {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+    'api-key': apiKey,
+    ...extra
+  };
 }
 
-function saveMemories(memories) {
-  const dir = dirname(MEMORIES_PATH);
+async function fetchApiJson(path, { apiKey, method = 'GET', body = undefined, headers = {} } = {}) {
+  const url = await buildSafeApiUrl(path);
+  const init = {
+    method,
+    headers: apiRequestHeaders(apiKey, headers),
+    ...(body === undefined ? {} : { body: JSON.stringify(body) })
+  };
+
+  const response = await fetch(url, init);
+  const text = await response.text();
+  let payload = {};
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { message: text };
+    }
+  }
+  if (!response.ok) {
+    const err = new Error(payload?.message || payload?.error?.message || response.statusText || 'Sogni API request failed');
+    err.code = 'API_REQUEST_FAILED';
+    err.details = { url, status: response.status, payload };
+    throw err;
+  }
+  return payload;
+}
+
+function getApiModeMediaReferences() {
+  const refs = [];
+  for (const value of options.contextImages || []) {
+    if (value) refs.push({ flag: '-c/--context', value, kind: 'image' });
+  }
+  if (options.refImage) refs.push({ flag: '--ref', value: options.refImage, kind: 'image' });
+  if (options.refImageEnd) refs.push({ flag: '--ref-end', value: options.refImageEnd, kind: 'image' });
+  if (options.refAudio) refs.push({ flag: '--ref-audio', value: options.refAudio, kind: 'audio' });
+  if (options.referenceAudioIdentity) refs.push({ flag: '--reference-audio-identity', value: options.referenceAudioIdentity, kind: 'audio' });
+  if (options.refVideo) refs.push({ flag: '--ref-video', value: options.refVideo, kind: 'video' });
+  return refs;
+}
+
+function formatApiMediaFlags(refs) {
+  return [...new Set(refs.map(ref => ref.flag))].join(', ');
+}
+
+function extractApiEnvelopeData(payload) {
+  return payload?.data && typeof payload.data === 'object' ? payload.data : payload;
+}
+
+function extractChatMessage(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.choices?.[0]?.message || data?.choices?.[0]?.delta || payload?.choices?.[0]?.message || {};
+}
+
+function extractChatWorkflows(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.creative_workflows || data?.creativeWorkflows || payload?.creative_workflows || payload?.creativeWorkflows || [];
+}
+
+function mimeTypeForPath(pathOrUrl, fallback = 'application/octet-stream') {
+  const clean = String(pathOrUrl || '').split('?')[0].toLowerCase();
+  if (clean.endsWith('.jpg') || clean.endsWith('.jpeg')) return 'image/jpeg';
+  if (clean.endsWith('.png')) return 'image/png';
+  if (clean.endsWith('.mp3')) return 'audio/mpeg';
+  if (clean.endsWith('.wav')) return 'audio/wav';
+  if (clean.endsWith('.m4a')) return 'audio/mp4';
+  if (clean.endsWith('.webm')) return 'audio/webm';
+  if (clean.endsWith('.ogg')) return 'audio/ogg';
+  if (clean.endsWith('.flac')) return 'audio/flac';
+  if (clean.endsWith('.mp4')) return 'video/mp4';
+  if (clean.endsWith('.mov')) return 'video/quicktime';
+  return fallback;
+}
+
+async function imageDataUriFromPathOrUrl(pathOrUrl) {
+  const mimeType = mimeTypeForPath(pathOrUrl);
+  if (mimeType !== 'image/jpeg' && mimeType !== 'image/png') {
+    const err = new Error(`API chat vision supports PNG or JPEG image references, got ${pathOrUrl}.`);
+    err.code = 'UNSUPPORTED_MEDIA_TYPE';
+    throw err;
+  }
+  const buffer = await fetchMediaBuffer(pathOrUrl);
+  return `data:${mimeType};base64,${buffer.toString('base64')}`;
+}
+
+async function buildApiChatMessages() {
+  const system = options.apiSystemPrompt ||
+    'You are a concise creative production assistant. Use Sogni creative tools when they help produce concrete media.';
+  const imageRefs = [
+    ...options.contextImages,
+    options.refImage,
+    options.refImageEnd
+  ].filter(Boolean);
+
+  const messages = [{ role: 'system', content: system }];
+  if (imageRefs.length === 0) {
+    messages.push({ role: 'user', content: options.prompt });
+    return messages;
+  }
+
+  if (options.apiToolExecution) {
+    const err = new Error(
+      '--api-chat with server-side tool execution does not currently support image references. ' +
+      'Use the direct CLI path for uploaded-media workflows, or pass --no-api-tool-execution for vision-only chat/planning.'
+    );
+    err.code = 'UNSUPPORTED_API_UPLOAD_EXECUTION';
+    throw err;
+  }
+
+  const content = [{ type: 'text', text: options.prompt || 'Describe the attached media.' }];
+  for (const ref of imageRefs) {
+    content.push({ type: 'image_url', image_url: { url: await imageDataUriFromPathOrUrl(ref) } });
+  }
+  messages.push({ role: 'user', content });
+  return messages;
+}
+
+async function runApiChat(log) {
+  const creds = loadCredentials();
+  const apiKey = requireApiKeyCredentials(creds, '--api-chat');
+  const body = {
+    model: options.llmModel || DEFAULT_LLM_MODEL,
+    messages: await buildApiChatMessages(),
+    temperature: 0.4,
+    max_tokens: 1600,
+    token_type: options.tokenType || 'spark',
+    app_source: SOGNI_APP_SOURCE,
+    appSource: SOGNI_APP_SOURCE,
+    sogni_tools: options.apiTools,
+    sogni_tool_execution: options.apiToolExecution
+  };
+  const payload = await fetchApiJson('/v1/chat/completions', {
+    apiKey,
+    method: 'POST',
+    body
+  });
+  const message = extractChatMessage(payload);
+  const workflows = extractChatWorkflows(payload);
+  const toolCalls = message.tool_calls || message.toolCalls || [];
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      type: 'api-chat',
+      content: message.content || '',
+      toolCalls,
+      creativeWorkflows: workflows,
+      raw: payload
+    }));
+    return;
+  }
+
+  if (message.content) console.log(message.content);
+  if (toolCalls.length > 0) {
+    console.log('\nTool calls:');
+    for (const call of toolCalls) {
+      console.log(`  - ${call.function?.name || call.name || call.id || 'tool_call'}`);
+    }
+  }
+  if (workflows.length > 0) {
+    console.log('\nCreative workflows:');
+    for (const workflow of workflows) {
+      console.log(`  - ${workflow.workflowId || workflow.id}: ${workflow.status || 'submitted'}`);
+    }
+  }
+  if (!message.content && toolCalls.length === 0 && workflows.length === 0) {
+    log('No API chat content returned.');
+  }
+}
+
+function parseWorkflowInput(raw) {
+  if (!raw) return null;
+  const sourcePath = raw.startsWith('@') ? raw.slice(1) : raw;
+  const expanded = expandHomePath(sourcePath);
+  const text = raw.startsWith('@') || existsSync(expanded)
+    ? readFileSync(expanded, 'utf8')
+    : raw;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const err = new Error(`Invalid --workflow-input JSON: ${error?.message || String(error)}`);
+    err.code = 'INVALID_WORKFLOW_INPUT';
+    throw err;
+  }
+}
+
+function buildImageToVideoWorkflowInput() {
+  const parsed = parseWorkflowInput(options.apiWorkflowInput);
+  if (parsed) return parsed;
+  const input = {
+    prompt: options.prompt
+  };
+  if (options.apiVideoPrompt) input.videoPrompt = options.apiVideoPrompt;
+  if (options.apiNegativePrompt) input.negativePrompt = options.apiNegativePrompt;
+  if (Number.isFinite(options.width)) input.width = options.width;
+  if (Number.isFinite(options.height)) input.height = options.height;
+  if (Number.isFinite(options.duration)) input.duration = options.duration;
+  if (options.model) input.imageModel = options.model;
+  if (options.videoModel) input.videoModel = options.videoModel;
+  if (Number.isFinite(options.count)) input.numberOfMedia = options.count;
+  if (options.seed !== null && options.seed !== undefined) input.seed = options.seed;
+  if (options.apiGenerateAudio !== null) input.generateAudio = options.apiGenerateAudio;
+  if (options.apiExpandPrompt !== null) input.expandPrompt = options.apiExpandPrompt;
+  return input;
+}
+
+function buildHostedToolSequenceWorkflowInput() {
+  const parsed = parseWorkflowInput(options.apiWorkflowInput);
+  if (!parsed) {
+    const err = new Error('--api-workflow hosted-tool-sequence requires --workflow-input JSON.');
+    err.code = 'MISSING_WORKFLOW_INPUT';
+    throw err;
+  }
+  if (options.apiWorkflowTitle && !parsed.title) {
+    parsed.title = options.apiWorkflowTitle;
+  }
+  return parsed;
+}
+
+function storyboardWorkflowImageQualityFromCli() {
+  if (!cliSet.quality || !options.quality) return undefined;
+  if (options.quality === 'pro') return 'high';
+  if (options.quality === 'fast') return 'low';
+  return 'medium';
+}
+
+function storyboardWorkflowInputFromParsedValue(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (Array.isArray(parsed.steps)) return parsed;
+
+  const storyline = typeof parsed.storyline === 'string'
+    ? parsed.storyline
+    : typeof parsed.script === 'string'
+      ? parsed.script
+      : typeof parsed.storyboardScript === 'string'
+        ? parsed.storyboardScript
+        : null;
+  if (!storyline) return null;
+  const explicitCliVideoModel = options.videoModel
+    || (cliSet.model && isSeedanceModelSelection(options.model) ? options.model : undefined);
+  const explicitCliImageModel = cliSet.model && !isSeedanceModelSelection(options.model) ? options.model : undefined;
+
+  return buildStoryboardVideoHostedToolSequenceInput({
+    storyline,
+    userIntentText: typeof parsed.userIntentText === 'string'
+      ? parsed.userIntentText
+      : typeof parsed.prompt === 'string'
+        ? parsed.prompt
+        : options.prompt || storyline,
+    title: typeof parsed.title === 'string' ? parsed.title : options.apiWorkflowTitle,
+    frameCount: typeof parsed.frameCount === 'number'
+      ? parsed.frameCount
+      : typeof parsed.storyboardFrames === 'number'
+        ? parsed.storyboardFrames
+        : options.storyboardFrames ?? undefined,
+    videoDurationSec: typeof parsed.videoDurationSec === 'number'
+      ? parsed.videoDurationSec
+      : cliSet.duration && Number.isFinite(options.duration)
+        ? options.duration
+        : undefined,
+    videoTargetResolution: Number.isFinite(parsed.videoTargetResolution)
+      ? parsed.videoTargetResolution
+      : cliSet.targetResolution && Number.isFinite(options.targetResolution)
+        ? options.targetResolution
+        : undefined,
+    imageModel: typeof parsed.imageModel === 'string' ? parsed.imageModel : explicitCliImageModel,
+    imageQuality: typeof parsed.imageQuality === 'string'
+      ? parsed.imageQuality
+      : typeof parsed.gptImageQuality === 'string'
+        ? parsed.gptImageQuality
+        : storyboardWorkflowImageQualityFromCli(),
+    imageOutputFormat: typeof parsed.imageOutputFormat === 'string'
+      ? parsed.imageOutputFormat
+      : typeof parsed.outputFormat === 'string'
+        ? parsed.outputFormat
+        : cliSet.outputFormat
+          ? options.outputFormat
+          : undefined,
+    videoModel: typeof parsed.videoModel === 'string' ? parsed.videoModel : explicitCliVideoModel,
+    generateAudio: typeof parsed.generateAudio === 'boolean' ? parsed.generateAudio : options.apiGenerateAudio ?? undefined,
+  });
+}
+
+function buildStoryboardStorylineMessages() {
+  const durationLine = cliSet.duration && Number.isFinite(options.duration)
+    ? `Target duration: ${options.duration} seconds.`
+    : 'Target duration: infer a Seedance-safe duration between 4 and 15 seconds from the request.';
+  const frameLine = Number.isFinite(options.storyboardFrames)
+    ? `Storyboard beat count: exactly ${options.storyboardFrames}.`
+    : 'Storyboard beat count: infer a compact 4-8 beat plan unless the user asks otherwise.';
+  const targetResolutionLine = cliSet.targetResolution && Number.isFinite(options.targetResolution)
+    ? `Video target short-side resolution: ${options.targetResolution}p.`
+    : '';
+  const system = [
+    'You write production-ready video storyboard storylines for a GPT Image 2 storyboard sheet that will be rendered into a Seedance 2.0 video.',
+    'Return only the storyline/script. Do not call tools, do not ask follow-up questions, and do not include markdown fences.',
+    'Use this exact plain-text structure so downstream compilers can parse it: Project Title, Total Duration, then one SCENE NN - Title block per beat.',
+    'Each scene block must put each field on its own line: TIME, PURPOSE, VISUAL, ACTION, CAMERA, LIGHTING/STYLE, TRANSITION, DIALOGUE/VO, AUDIO/SFX, MUSIC, VISIBLE TEXT.',
+    'When there is no spoken dialogue or voiceover, write DIALOGUE/VO: [no dialogue]. Do not write None, N/A, or leave it blank.',
+    'If the user requires exact visible text, repeat that exact text only in the relevant VISIBLE TEXT field and preserve spelling exactly.',
+    'Keep it concise enough for one GPT Image 2 storyboard image and one Seedance video prompt, while preserving cause-and-effect story progression.',
+  ].join(' ');
+  const user = [
+    'Original user request:',
+    options.prompt,
+    '',
+    durationLine,
+    frameLine,
+    targetResolutionLine,
+  ].filter(Boolean).join('\n');
+  return [
+    { role: 'system', content: system },
+    { role: 'user', content: user },
+  ];
+}
+
+async function generateStoryboardWorkflowStoryline(apiKey) {
+  const payload = await fetchApiJson('/v1/chat/completions', {
+    apiKey,
+    method: 'POST',
+    body: {
+      model: options.llmModel || DEFAULT_LLM_MODEL,
+      messages: buildStoryboardStorylineMessages(),
+      temperature: 0.45,
+      max_tokens: 1800,
+      token_type: options.tokenType || 'spark',
+      app_source: SOGNI_APP_SOURCE,
+      appSource: SOGNI_APP_SOURCE,
+      sogni_tools: false,
+      sogni_tool_execution: false
+    }
+  });
+  const message = extractChatMessage(payload);
+  const storyline = typeof message.content === 'string' ? message.content.trim() : '';
+  if (!storyline) {
+    const err = new Error('Storyboard-video planning did not return a storyline.');
+    err.code = 'EMPTY_STORYBOARD_STORYLINE';
+    err.details = { payload };
+    throw err;
+  }
+  return { storyline, raw: payload };
+}
+
+async function buildStoryboardVideoWorkflowInput(apiKey) {
+  const parsed = parseWorkflowInput(options.apiWorkflowInput);
+  const parsedPlan = storyboardWorkflowInputFromParsedValue(parsed);
+  if (parsedPlan) {
+    return parsedPlan.input ? { plan: parsedPlan, planningRaw: null } : { plan: { input: parsedPlan }, planningRaw: null };
+  }
+
+  const { storyline, raw } = await generateStoryboardWorkflowStoryline(apiKey);
+  const explicitCliVideoModel = options.videoModel
+    || (cliSet.model && isSeedanceModelSelection(options.model) ? options.model : undefined);
+  const explicitCliImageModel = cliSet.model && !isSeedanceModelSelection(options.model) ? options.model : undefined;
+  const plan = buildStoryboardVideoHostedToolSequenceInput({
+    storyline,
+    userIntentText: options.prompt,
+    title: options.apiWorkflowTitle,
+    frameCount: options.storyboardFrames ?? undefined,
+    videoDurationSec: cliSet.duration && Number.isFinite(options.duration) ? options.duration : undefined,
+    videoTargetResolution: cliSet.targetResolution && Number.isFinite(options.targetResolution) ? options.targetResolution : undefined,
+    imageModel: explicitCliImageModel,
+    imageQuality: storyboardWorkflowImageQualityFromCli(),
+    imageOutputFormat: cliSet.outputFormat ? options.outputFormat : undefined,
+    videoModel: explicitCliVideoModel,
+    generateAudio: options.apiGenerateAudio ?? undefined,
+  });
+  return { plan, planningRaw: raw };
+}
+
+function workflowFromPayload(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.workflow || payload?.workflow || payload;
+}
+
+function workflowsFromPayload(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.workflows || payload?.workflows || [];
+}
+
+function eventsFromPayload(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.events || payload?.events || [];
+}
+
+function printWorkflowSummary(workflow) {
+  console.log(`Workflow: ${workflow.workflowId || workflow.id || '(unknown)'}`);
+  if (workflow.kind) console.log(`Kind:     ${workflow.kind}`);
+  if (workflow.status) console.log(`Status:   ${workflow.status}`);
+  if (workflow.title) console.log(`Title:    ${workflow.title}`);
+  const artifacts = Array.isArray(workflow.artifacts) ? workflow.artifacts : [];
+  if (artifacts.length > 0) {
+    console.log('\nArtifacts:');
+    for (const artifact of artifacts) {
+      console.log(`  - ${artifact.type || artifact.mediaType || 'artifact'}: ${artifact.url || artifact.id || JSON.stringify(artifact)}`);
+    }
+  }
+}
+
+function printWorkflowSseFrames(raw) {
+  const frames = typeof parseCreativeWorkflowSseChunk === 'function'
+    ? parseCreativeWorkflowSseChunk(raw)
+    : parseWorkflowSseChunk(raw);
+  for (const frame of frames) {
+    const data = frame.data && typeof frame.data === 'object' ? frame.data : {};
+    const suffix = data.status ? ` ${data.status}` : data.message ? ` ${data.message}` : '';
+    console.log(`[${frame.id || '-'}] ${frame.event}${suffix}`);
+  }
+}
+
+function parseWorkflowSseChunk(raw) {
+  const frames = [];
+  const chunks = String(raw || '').split(/\r?\n\r?\n/).filter(chunk => chunk.trim());
+  for (const chunk of chunks) {
+    const frame = { id: null, event: 'message', data: null };
+    const dataLines = [];
+    for (const line of chunk.split(/\r?\n/)) {
+      if (!line || line.startsWith(':')) continue;
+      const separator = line.indexOf(':');
+      const field = separator >= 0 ? line.slice(0, separator) : line;
+      const value = separator >= 0 ? line.slice(separator + 1).replace(/^ /, '') : '';
+      if (field === 'id') frame.id = value;
+      else if (field === 'event') frame.event = value || 'message';
+      else if (field === 'data') dataLines.push(value);
+    }
+    if (dataLines.length > 0) {
+      const dataText = dataLines.join('\n');
+      try {
+        frame.data = JSON.parse(dataText);
+      } catch {
+        frame.data = { message: dataText };
+      }
+    }
+    frames.push(frame);
+  }
+  return frames;
+}
+
+async function streamApiWorkflowEvents(apiKey, workflowId) {
+  const url = await buildSafeApiUrl(`/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/events/stream`);
+
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: apiRequestHeaders(apiKey, { Accept: 'text/event-stream' })
+  });
+  if (!response.ok) {
+    const err = new Error(`Workflow stream failed (${response.status} ${response.statusText})`);
+    err.code = 'API_STREAM_FAILED';
+    throw err;
+  }
+  if (!response.body) return;
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.search(/\r?\n\r?\n/);
+      while (boundary !== -1) {
+        const chunk = buffer.slice(0, boundary);
+        const match = buffer.slice(boundary).match(/^\r?\n\r?\n/);
+        buffer = buffer.slice(boundary + (match?.[0].length || 2));
+        printWorkflowSseFrames(chunk);
+        boundary = buffer.search(/\r?\n\r?\n/);
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim()) {
+      printWorkflowSseFrames(buffer);
+    }
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+async function runApiWorkflow() {
+  const creds = loadCredentials();
+  const apiKey = requireApiKeyCredentials(creds, '--api-workflow');
+  const tokenType = options.tokenType || 'spark';
+  let payload;
+  let type = 'api-workflow';
+
+  if (options.apiWorkflowAction === 'list') {
+    payload = await fetchApiJson('/v1/creative-agent/workflows?limit=20', { apiKey });
+    const workflows = workflowsFromPayload(payload);
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, type, action: 'list', workflows, raw: payload }));
+    } else {
+      for (const workflow of workflows) {
+        console.log(`${workflow.workflowId || workflow.id}\t${workflow.status || '-'}\t${workflow.title || ''}`);
+      }
+    }
+    return;
+  }
+
+  if (options.apiWorkflowAction === 'get' || options.apiWorkflowAction === 'events' || options.apiWorkflowAction === 'stream' || options.apiWorkflowAction === 'cancel') {
+    const id = options.apiWorkflowId;
+    if (!id) {
+      const err = new Error('Workflow id is required.');
+      err.code = 'MISSING_WORKFLOW_ID';
+      throw err;
+    }
+    if (options.apiWorkflowAction === 'stream') {
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, type, action: 'stream', workflowId: id, note: 'Streaming writes SSE frames as text output.' }));
+      }
+      await streamApiWorkflowEvents(apiKey, id);
+      return;
+    }
+    const path = options.apiWorkflowAction === 'events'
+      ? `/v1/creative-agent/workflows/${encodeURIComponent(id)}/events`
+      : options.apiWorkflowAction === 'cancel'
+        ? `/v1/creative-agent/workflows/${encodeURIComponent(id)}/cancel`
+        : `/v1/creative-agent/workflows/${encodeURIComponent(id)}`;
+    payload = await fetchApiJson(path, {
+      apiKey,
+      method: options.apiWorkflowAction === 'cancel' ? 'POST' : 'GET'
+    });
+    if (options.apiWorkflowAction === 'events') {
+      const events = eventsFromPayload(payload);
+      if (options.json) console.log(JSON.stringify({ success: true, type, action: 'events', workflowId: id, events, raw: payload }));
+      else console.log(JSON.stringify(events, null, 2));
+      return;
+    }
+    const workflow = workflowFromPayload(payload);
+    if (options.json) console.log(JSON.stringify({ success: true, type, action: options.apiWorkflowAction, workflow, raw: payload }));
+    else printWorkflowSummary(workflow);
+    return;
+  }
+
+  const requestedKind = options.apiWorkflowKind || 'image_to_video';
+  let kind = requestedKind;
+  let input;
+  let storyboardPlan = null;
+  let storyboardPlanningRaw = null;
+
+  if (requestedKind === 'storyboard_video') {
+    const built = await buildStoryboardVideoWorkflowInput(apiKey);
+    storyboardPlan = built.plan;
+    storyboardPlanningRaw = built.planningRaw;
+    kind = 'hosted_tool_sequence';
+    input = storyboardPlan.input;
+  } else {
+    input = requestedKind === 'hosted_tool_sequence'
+      ? buildHostedToolSequenceWorkflowInput()
+      : buildImageToVideoWorkflowInput();
+  }
+
+  payload = await fetchApiJson('/v1/creative-agent/workflows', {
+    apiKey,
+    method: 'POST',
+    headers: options.apiWorkflowIdempotencyKey
+      ? { 'Idempotency-Key': options.apiWorkflowIdempotencyKey }
+      : {},
+    body: {
+      kind,
+      input,
+      ...(options.apiWorkflowIdempotencyKey ? { idempotency_key: options.apiWorkflowIdempotencyKey } : {}),
+      token_type: tokenType,
+      app_source: SOGNI_APP_SOURCE,
+      appSource: SOGNI_APP_SOURCE
+    }
+  });
+  const workflow = workflowFromPayload(payload);
+  const workflowId = workflow?.workflowId || workflow?.id;
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      type,
+      action: 'start',
+      workflowKind: requestedKind,
+      ...(storyboardPlan ? {
+        storyline: storyboardPlan.storyline,
+        storyboardPlan: {
+          title: storyboardPlan.title,
+          frameCount: storyboardPlan.frameCount,
+          image: storyboardPlan.image,
+          video: storyboardPlan.video,
+          warnings: storyboardPlan.warnings,
+        },
+      } : {}),
+      workflow,
+      raw: payload,
+      ...(storyboardPlanningRaw ? { planningRaw: storyboardPlanningRaw } : {}),
+    }));
+  } else {
+    if (storyboardPlan?.storyline) {
+      console.log('Generated storyline:\n');
+      console.log(storyboardPlan.storyline);
+      console.log('');
+    }
+    printWorkflowSummary(workflow);
+  }
+  if (options.apiWorkflowWatch && workflowId) {
+    await streamApiWorkflowEvents(apiKey, workflowId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Memory system — persistent user preferences on disk
+// ---------------------------------------------------------------------------
+const MEMORIES_PATH = getEnv('SOGNI_MEMORIES_PATH') || DEFAULT_MEMORIES_PATH;
+
+function loadMemories() {
+  try {
+    if (existsSync(MEMORIES_PATH)) return JSON.parse(readFileSync(MEMORIES_PATH, 'utf8'));
+  } catch {}
+  return [];
+}
+
+function saveMemories(memories) {
+  const dir = dirname(MEMORIES_PATH);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(MEMORIES_PATH, JSON.stringify(memories, null, 2));
 }
@@ -2569,6 +3882,176 @@ async function fetchMediaBuffer(pathOrUrl) {
   }
 }
 
+async function fetchMediaBlob(pathOrUrl, fallbackMimeType = 'application/octet-stream') {
+  if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
+    await assertSafeUrl(pathOrUrl);
+    const response = await fetch(pathOrUrl);
+    if (!response.ok) {
+      const err = new Error(`Failed to fetch media (${response.status} ${response.statusText})`);
+      err.code = 'FETCH_FAILED';
+      err.details = { url: pathOrUrl, status: response.status, statusText: response.statusText };
+      throw err;
+    }
+    const contentType = response.headers.get('content-type')?.split(';')[0]?.trim();
+    const mimeType = contentType || mimeTypeForPath(pathOrUrl, fallbackMimeType);
+    return new Blob([await response.arrayBuffer()], { type: mimeType });
+  }
+
+  const buffer = await fetchMediaBuffer(pathOrUrl);
+  return new Blob([buffer], { type: mimeTypeForPath(pathOrUrl, fallbackMimeType) });
+}
+
+async function prepareReferenceAudioIdentityMedia(pathOrUrl) {
+  const cleanExt = extname(String(pathOrUrl || '').split('?')[0]).toLowerCase();
+  if (!pathOrUrl.startsWith('http://') && !pathOrUrl.startsWith('https://') && (cleanExt === '.wav' || cleanExt === '.wave')) {
+    const sourcePath = sanitizePath(pathOrUrl, '--reference-audio-identity');
+    const ffmpegPath = await ensureFfmpegAvailable();
+    const tempDir = mkdtempSync(join(tmpdir(), 'sogni-audio-id-'));
+    const outputPath = join(tempDir, 'voice-identity.m4a');
+    try {
+      const result = await runCommand(ffmpegPath, [
+        '-hide_banner',
+        '-loglevel', 'error',
+        '-y',
+        '-i', sourcePath,
+        '-vn',
+        '-ac', '1',
+        '-c:a', 'aac',
+        '-b:a', '96k',
+        outputPath
+      ], { captureOutput: true });
+
+      if (result.error || result.status !== 0 || !isNonEmptyFile(outputPath)) {
+        const err = new Error('Failed to normalize WAV voice identity audio to M4A.');
+        err.code = 'FFMPEG_AUDIO_ID_FAILED';
+        err.hint = 'Provide an .m4a/.mp3/.webm voice clip, or install ffmpeg so WAV clips can be converted.';
+        err.details = { sourcePath, stderr: result.stderr || '', stdout: result.stdout || '', status: result.status };
+        throw err;
+      }
+
+      const buffer = readFileSync(outputPath);
+      return new Blob([buffer], { type: 'audio/mp4' });
+    } finally {
+      try { if (existsSync(outputPath)) unlinkSync(outputPath); } catch {}
+      try { rmdirSync(tempDir); } catch {}
+    }
+  }
+
+  return fetchMediaBlob(pathOrUrl, 'audio/mp4');
+}
+
+function mediaTempInputPath(tempDir, sourceLabel, fallbackExt) {
+  const cleanExt = extname(String(sourceLabel || '').split('?')[0]).toLowerCase();
+  const ext = /^[.][a-z0-9]{1,8}$/i.test(cleanExt) ? cleanExt : fallbackExt;
+  return join(tempDir, `input${ext}`);
+}
+
+async function transcodeMp3ReferenceAudioBuffer(buffer, sourceLabel) {
+  const ffmpegPath = await ensureFfmpegAvailable();
+  const tempDir = mkdtempSync(join(tmpdir(), 'sogni-ref-audio-'));
+  const inputPath = mediaTempInputPath(tempDir, sourceLabel, '.mp3');
+  const outputPath = join(tempDir, 'reference-audio.m4a');
+  try {
+    writeFileSync(inputPath, buffer);
+    const result = await runCommand(ffmpegPath, [
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-y',
+      '-i', inputPath,
+      '-vn',
+      '-c:a', 'aac',
+      '-b:a', '192k',
+      '-movflags', '+faststart',
+      outputPath
+    ], { captureOutput: true });
+
+    if (result.error || result.status !== 0 || !isNonEmptyFile(outputPath)) {
+      const err = new Error('Failed to prepare MP3 reference audio for video generation.');
+      err.code = 'FFMPEG_AUDIO_PREP_FAILED';
+      err.hint = 'Install ffmpeg with AAC support, or provide M4A/WAV reference audio.';
+      err.details = { sourceLabel, stderr: result.stderr || '', stdout: result.stdout || '', status: result.status };
+      throw err;
+    }
+
+    return readFileSync(outputPath);
+  } finally {
+    try { if (existsSync(inputPath)) unlinkSync(inputPath); } catch {}
+    try { if (existsSync(outputPath)) unlinkSync(outputPath); } catch {}
+    try { rmdirSync(tempDir); } catch {}
+  }
+}
+
+async function prepareReferenceAudioForVideoBuffer(buffer, sourceLabel) {
+  const mimeType = mimeTypeForPath(sourceLabel, 'application/octet-stream');
+  const sourceFormat = detectReferenceAudioFormat(buffer, mimeType);
+  if (sourceFormat !== 'mp3') return buffer;
+
+  const prepared = await transcodeMp3ReferenceAudioBuffer(buffer, sourceLabel);
+  if (!options.quiet) {
+    console.error('Prepared MP3 reference audio as M4A for video provider compatibility.');
+  }
+  return prepared;
+}
+
+async function trimSeedanceV2VSourceVideoBuffer(buffer, sourceLabel, startOffset, requestedDuration) {
+  const ffmpegPath = await ensureFfmpegAvailable();
+  const tempDir = mkdtempSync(join(tmpdir(), 'sogni-seedance-v2v-'));
+  const inputPath = mediaTempInputPath(tempDir, sourceLabel, '.mp4');
+  const outputPath = join(tempDir, 'seedance-source.mp4');
+  const start = Math.max(0, Number(startOffset) || 0);
+  const duration = Math.max(
+    0.1,
+    Math.min(SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS, Number(requestedDuration) || SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS),
+  );
+  try {
+    writeFileSync(inputPath, buffer);
+    const result = await runCommand(ffmpegPath, [
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-y',
+      '-ss', String(start),
+      '-i', inputPath,
+      '-t', String(duration),
+      '-map', '0:v:0',
+      '-an',
+      '-c:v', 'libx264',
+      '-preset', 'veryfast',
+      '-crf', '18',
+      '-pix_fmt', 'yuv420p',
+      '-movflags', '+faststart',
+      outputPath
+    ], { captureOutput: true });
+
+    if (result.error || result.status !== 0 || !isNonEmptyFile(outputPath)) {
+      const err = new Error('Failed to prepare Seedance video-to-video reference clip.');
+      err.code = 'FFMPEG_SEEDANCE_V2V_PREP_FAILED';
+      err.hint = 'Install ffmpeg with libx264 support, or provide a reference clip that starts at the desired frame.';
+      err.details = { sourceLabel, start, duration, stderr: result.stderr || '', stdout: result.stdout || '', status: result.status };
+      throw err;
+    }
+
+    return readFileSync(outputPath);
+  } finally {
+    try { if (existsSync(inputPath)) unlinkSync(inputPath); } catch {}
+    try { if (existsSync(outputPath)) unlinkSync(outputPath); } catch {}
+    try { rmdirSync(tempDir); } catch {}
+  }
+}
+
+async function appendSafeSeedanceReferenceUrl(target, pathOrUrl, label) {
+  if (!isHttpsUrl(pathOrUrl)) return false;
+  try {
+    await assertSafeUrl(pathOrUrl, { allowedProtocols: ['https:'] });
+  } catch (error) {
+    const err = new Error(`${label} URL is not safe to forward: ${error?.message || String(error)}`);
+    err.code = 'INVALID_URL';
+    err.details = { url: pathOrUrl, label };
+    throw err;
+  }
+  target.push(pathOrUrl);
+  return true;
+}
+
 function resolveMultiAngleOutputConfig(outputPath, outputFormat) {
   if (!outputPath) return null;
   const ext = extname(outputPath);
@@ -2815,7 +4298,7 @@ async function runImageEditProjectWithEvents(client, editConfig, expectedCount,
     if (!projectId) projectId = data.projectId;
     const jobData = data.job?.data || {};
     results.push({
-      imageUrl: data.imageUrl,
+      resultUrl: data.resultUrl || data.imageUrl,
       seed: jobData.seed,
       jobIndex: data.jobIndex,
       projectId: data.projectId
@@ -2966,7 +4449,7 @@ async function runMultiAngleFlow(client, log) {
       options.timeout,
       azimuth
     );
-    const urls = results.map((r) => r.imageUrl).filter(Boolean);
+    const urls = results.map((r) => r.resultUrl).filter(Boolean);
     const seeds = results.map((r) => r.seed ?? options.seed);
 
     if (outputConfig) {
@@ -3284,12 +4767,21 @@ async function ensureSufficientVideoBalance(client, log) {
 
 // ---------------------------------------------------------------------------
 // Token auto-fallback: resolve 'auto' to 'spark', retry with 'sogni' on
-// insufficient balance errors.
+// insufficient balance errors for native Sogni models. External API-backed
+// models are Spark-only and must not silently fall back to SOGNI tokens.
 // ---------------------------------------------------------------------------
+const _requiresSparkOnlyToken = requiresSparkOnlyToken(options.model);
+if (_requiresSparkOnlyToken && options.tokenType === 'sogni') {
+  if (!options.quiet) {
+    console.error(`${options.model} requires SPARK tokens; using --token-type spark.`);
+  }
+  options.tokenType = 'spark';
+}
 const _isAutoToken = options.tokenType === 'auto';
 if (_isAutoToken) {
   options.tokenType = 'spark';
 }
+const _allowAutoTokenFallback = _isAutoToken && !_requiresSparkOnlyToken;
 
 async function main() {
   let exitCode = 0;
@@ -3448,6 +4940,16 @@ async function main() {
       }
     }
 
+    if (options.apiChat) {
+      await runApiChat(log);
+      return;
+    }
+
+    if (options.apiWorkflowAction) {
+      await runApiWorkflow(log);
+      return;
+    }
+
     if (options.extractLastFrame) {
       const videoPath = sanitizePath(options.extractLastFrame, '--extract-last-frame video');
       const outputPath = sanitizePath(options.extractLastFrameOutput, '--extract-last-frame output');
@@ -3574,18 +5076,15 @@ async function main() {
     const creds = loadCredentials();
     log('Connecting to Sogni...');
     client = new SogniClientWrapper({
+      appSource: SOGNI_APP_SOURCE,
       network: openclawConfig?.defaultNetwork || 'fast',
       autoConnect: false,
-      ...(creds.SOGNI_API_KEY
-        ? { apiKey: creds.SOGNI_API_KEY, authType: 'apiKey' }
-        : {
-            username: creds.SOGNI_USERNAME,
-            password: creds.SOGNI_PASSWORD,
-            authType: 'token'
-          })
+      apiKey: creds.SOGNI_API_KEY,
+      authType: 'apiKey'
     });
 
     await client.connect();
+    await disableLiveModelAvailabilityEvents(client);
     log('Connected.');
 
     if (options.showBalance) {
@@ -3667,14 +5166,13 @@ async function main() {
       client.on(ClientEvent.JOB_COMPLETED, (data) => {
         const jobData = data.job?.data || {};
         results.push({
-          imageUrl: data.imageUrl,
-          videoUrl: data.videoUrl,
+          resultUrl: data.resultUrl || (options.music ? data.audioUrl : options.video ? data.videoUrl : data.imageUrl),
           seed: jobData.seed,
           jobIndex: data.jobIndex,
           projectId: data.projectId
         });
         completedJobs++;
-        log(`${options.video ? 'Video' : 'Image'} ${completedJobs}/${options.count} completed`);
+        log(`${options.music ? 'Music' : options.video ? 'Video' : 'Image'} ${completedJobs}/${options.count} completed`);
         
         if (completedJobs >= options.count) {
           clearTimeout(timeout);
@@ -3707,8 +5205,8 @@ async function main() {
         reject(new Error(message));
       });
       
-      // Progress for video
-      if (options.video) {
+      // Progress for longer-running media jobs.
+      if (options.video || options.music) {
         client.on(ClientEvent.PROJECT_PROGRESS, (data) => {
           if (data.percentage && data.percentage > 0) {
             log(`Progress: ${Math.round(data.percentage)}%`);
@@ -3730,20 +5228,50 @@ async function main() {
       const seedanceReferenceImageUrls = [];
       const seedanceReferenceVideoUrls = [];
       const seedanceReferenceAudioUrls = [];
-      const useRefImageUrl = isSeedanceVideo && isHttpsUrl(options.refImage);
-      const useRefImageEndUrl = isSeedanceVideo && isHttpsUrl(options.refImageEnd);
-      const useRefAudioUrl = isSeedanceVideo && isHttpsUrl(options.refAudio);
-      const useRefVideoUrl = isSeedanceVideo && isHttpsUrl(options.refVideo);
-      if (useRefImageUrl) seedanceReferenceImageUrls.push(options.refImage);
-      if (useRefImageEndUrl) seedanceReferenceImageUrls.push(options.refImageEnd);
-      if (useRefAudioUrl) seedanceReferenceAudioUrls.push(options.refAudio);
-      if (useRefVideoUrl) seedanceReferenceVideoUrls.push(options.refVideo);
+      const useRefImageUrl = isSeedanceVideo && await appendSafeSeedanceReferenceUrl(seedanceReferenceImageUrls, options.refImage, 'Reference image');
+      const useRefImageEndUrl = isSeedanceVideo && await appendSafeSeedanceReferenceUrl(seedanceReferenceImageUrls, options.refImageEnd, 'End reference image');
+      const refAudioFormatByPath = options.refAudio
+        ? detectReferenceAudioFormat(new Uint8Array(), mimeTypeForPath(options.refAudio, 'application/octet-stream'))
+        : 'unknown';
+      const useRefAudioUrl = isSeedanceVideo
+        && refAudioFormatByPath !== 'mp3'
+        && await appendSafeSeedanceReferenceUrl(seedanceReferenceAudioUrls, options.refAudio, 'Reference audio');
+      const useRefVideoUrl = isSeedanceVideo
+        && options.videoStart === null
+        && await appendSafeSeedanceReferenceUrl(seedanceReferenceVideoUrls, options.refVideo, 'Reference video');
 
       let imageBuffer = options.refImage && !useRefImageUrl ? await fetchMediaBuffer(options.refImage) : undefined;
       let endImageBuffer = options.refImageEnd && !useRefImageEndUrl ? await fetchMediaBuffer(options.refImageEnd) : undefined;
-      const audioBuffer = options.refAudio && !useRefAudioUrl ? await fetchMediaBuffer(options.refAudio) : undefined;
-      const videoBuffer = options.refVideo && !useRefVideoUrl ? await fetchMediaBuffer(options.refVideo) : undefined;
-      const audioIdentityBuffer = options.referenceAudioIdentity ? await fetchMediaBuffer(options.referenceAudioIdentity) : undefined;
+      let audioBuffer = options.refAudio && !useRefAudioUrl ? await fetchMediaBuffer(options.refAudio) : undefined;
+      let videoBuffer = options.refVideo && !useRefVideoUrl ? await fetchMediaBuffer(options.refVideo) : undefined;
+      let projectVideoStart = options.videoStart;
+      if (audioBuffer) {
+        audioBuffer = await prepareReferenceAudioForVideoBuffer(audioBuffer, options.refAudio);
+      }
+      if (
+        videoBuffer
+        && isSeedanceVideo
+        && options.videoWorkflow === 'v2v'
+        && shouldTrimSeedanceV2VSourceVideo({
+          sourceDurationSeconds: null,
+          requestedDurationSeconds: options.duration,
+          startOffsetSeconds: options.videoStart ?? 0
+        })
+      ) {
+        videoBuffer = await trimSeedanceV2VSourceVideoBuffer(
+          videoBuffer,
+          options.refVideo,
+          options.videoStart ?? 0,
+          options.duration,
+        );
+        projectVideoStart = null;
+        if (!options.quiet) {
+          console.error('Prepared Seedance V2V reference video clip before upload.');
+        }
+      }
+      const audioIdentityMedia = options.referenceAudioIdentity
+        ? await prepareReferenceAudioIdentityMedia(options.referenceAudioIdentity)
+        : undefined;
       const modelDefaults = getModelDefaults(options.model, openclawConfig);
       const videoDimensionRules = videoDimensionRulesFromDefaults(modelDefaults, options.model);
 
@@ -3823,8 +5351,8 @@ async function main() {
       if (options.audioDuration !== null) {
         projectConfig.audioDuration = options.audioDuration;
       }
-      if (audioIdentityBuffer) {
-        projectConfig.referenceAudioIdentity = audioIdentityBuffer;
+      if (audioIdentityMedia) {
+        projectConfig.referenceAudioIdentity = audioIdentityMedia;
       }
       if (videoBuffer) {
         projectConfig.referenceVideo = videoBuffer;
@@ -3838,8 +5366,8 @@ async function main() {
       if (seedanceReferenceAudioUrls.length > 0) {
         projectConfig.referenceAudioUrls = seedanceReferenceAudioUrls;
       }
-      if (options.videoStart !== null) {
-        projectConfig.videoStart = options.videoStart;
+      if (projectVideoStart !== null) {
+        projectConfig.videoStart = projectVideoStart;
       }
       if (options.seed !== null && options.seed !== undefined) {
         projectConfig.seed = options.seed;
@@ -3890,6 +5418,67 @@ async function main() {
       if (videoResult?.error || videoResult?.message) {
         throw new Error(videoResult.error || videoResult.message);
       }
+    } else if (options.music) {
+      log(`Generating music with ${options.model}...`);
+      if (options.seed !== null && options.seed !== undefined) log(`Using seed: ${options.seed}`);
+
+      const projectConfig = {
+        modelId: options.model,
+        positivePrompt: options.prompt,
+        numberOfMedia: options.count,
+        duration: options.duration,
+        steps: options.steps,
+        tokenType: options.tokenType || 'spark',
+        waitForCompletion: false,
+        disableNSFWFilter: options.noFilter === true,
+        outputFormat: options.outputFormat || 'mp3'
+      };
+
+      if (options.guidance !== null && options.guidance !== undefined) {
+        projectConfig.guidance = options.guidance;
+      }
+      if (options.sampler) {
+        projectConfig.sampler = options.sampler;
+      }
+      if (options.scheduler) {
+        projectConfig.scheduler = options.scheduler;
+      }
+      if (options.musicShift !== null && options.musicShift !== undefined) {
+        projectConfig.shift = options.musicShift;
+      }
+      if (options.musicBpm !== null && options.musicBpm !== undefined) {
+        projectConfig.bpm = options.musicBpm;
+      }
+      if (options.musicTimesig) {
+        projectConfig.timesignature = options.musicTimesig;
+      }
+      if (options.musicLanguage) {
+        projectConfig.language = options.musicLanguage;
+      }
+      if (options.musicLyrics) {
+        projectConfig.lyrics = options.musicLyrics;
+      }
+      if (options.musicKeyscale) {
+        projectConfig.keyscale = options.musicKeyscale;
+      }
+      if (options.musicComposerMode !== null && options.musicComposerMode !== undefined) {
+        projectConfig.composerMode = options.musicComposerMode;
+      }
+      if (options.musicPromptStrength !== null && options.musicPromptStrength !== undefined) {
+        projectConfig.promptStrength = options.musicPromptStrength;
+      }
+      if (options.musicCreativity !== null && options.musicCreativity !== undefined) {
+        projectConfig.creativity = options.musicCreativity;
+      }
+      if (options.seed !== null && options.seed !== undefined) {
+        projectConfig.seed = options.seed;
+      }
+
+      const audioResult = await client.createAudioProject(projectConfig);
+
+      if (audioResult?.error || audioResult?.message) {
+        throw new Error(audioResult.error || audioResult.message);
+      }
     } else if (options.contextImages.length > 0) {
       // Image editing with context images
       log(`Editing with ${options.model}...`);
@@ -3903,6 +5492,13 @@ async function main() {
       const modelDefaults = getModelDefaults(options.model, openclawConfig);
       const steps = options.steps ?? modelDefaults?.steps ?? (options.model.includes('lightning') ? 4 : 20);
       const guidance = options.guidance ?? modelDefaults?.guidance ?? (options.model.includes('lightning') ? 3.5 : 7.5);
+      const gptImageQuality = isGptImage2ModelSelection(options.model)
+        ? options.quality === 'pro'
+          ? 'high'
+          : options.quality === 'fast'
+            ? 'low'
+            : 'medium'
+        : null;
       
       const editConfig = {
         modelId: options.model,
@@ -3920,6 +5516,9 @@ async function main() {
       if (options.outputFormat) {
         editConfig.outputFormat = options.outputFormat;
       }
+      if (gptImageQuality) {
+        editConfig.gptImageQuality = gptImageQuality;
+      }
       if (options.sampler) {
         editConfig.sampler = options.sampler;
       }
@@ -3937,7 +5536,11 @@ async function main() {
         editConfig.seed = options.seed;
       }
       
-      await client.createImageEditProject(editConfig);
+      if (isGptImage2ModelSelection(options.model)) {
+        await client.createImageProject(editConfig);
+      } else {
+        await client.createImageEditProject(editConfig);
+      }
     } else if (options.photobooth) {
       // Photobooth: face transfer with InstantID ControlNet
       log(`Photobooth with ${options.model}...`);
@@ -3992,6 +5595,13 @@ async function main() {
       const modelDefaults = getModelDefaults(options.model, openclawConfig);
       const guidance = options.guidance ?? modelDefaults?.guidance ?? 1.0;
       const steps = options.steps ?? modelDefaults?.steps;
+      const gptImageQuality = isGptImage2ModelSelection(options.model)
+        ? options.quality === 'pro'
+          ? 'high'
+          : options.quality === 'fast'
+            ? 'low'
+            : 'medium'
+        : null;
 
       const useVariations = options.count > 1 && hasPromptVariations(options.prompt);
       const variationCount = useVariations ? options.count : 1;
@@ -4024,6 +5634,9 @@ async function main() {
         if (options.outputFormat) {
           projectConfig.outputFormat = options.outputFormat;
         }
+        if (gptImageQuality) {
+          projectConfig.gptImageQuality = gptImageQuality;
+        }
         if (options.sampler) {
           projectConfig.sampler = options.sampler;
         }
@@ -4046,18 +5659,18 @@ async function main() {
     await completionPromise;
     
     if (results.length > 0) {
-      const urls = results.map(r => options.video ? r.videoUrl : r.imageUrl).filter(Boolean);
+      const urls = results.map(r => r.resultUrl).filter(Boolean);
       const firstResult = results[0];
       
       // Save last render info
       const seeds = results.map(r => r.seed ?? options.seed);
       const renderInfo = {
         timestamp: new Date().toISOString(),
-        type: options.video ? 'video' : 'image',
+        type: options.music ? 'music' : options.video ? 'video' : 'image',
         prompt: options.prompt,
         model: options.model,
-        width: options.width,
-        height: options.height,
+        width: options.music ? null : options.width,
+        height: options.music ? null : options.height,
         seed: firstResult.seed ?? options.seed,
         seedStrategy: options.seedStrategy || null,
         seeds,
@@ -4082,6 +5695,23 @@ async function main() {
       if (options.loraStrengths.length > 0) {
         renderInfo.loraStrengths = options.loraStrengths;
       }
+      if (options.music) {
+        renderInfo.duration = options.duration;
+        renderInfo.bpm = options.musicBpm ?? null;
+        renderInfo.keyscale = options.musicKeyscale || null;
+        renderInfo.timesignature = options.musicTimesig || null;
+        renderInfo.language = options.musicLanguage || null;
+        renderInfo.composerMode = options.musicComposerMode;
+        if (options.musicPromptStrength !== null && options.musicPromptStrength !== undefined) {
+          renderInfo.promptStrength = options.musicPromptStrength;
+        }
+        if (options.musicCreativity !== null && options.musicCreativity !== undefined) {
+          renderInfo.creativity = options.musicCreativity;
+        }
+        if (options.musicShift !== null && options.musicShift !== undefined) {
+          renderInfo.shift = options.musicShift;
+        }
+      }
       if (options.video) {
         renderInfo.workflow = options.videoWorkflow;
         renderInfo.fps = options.fps;
@@ -4182,17 +5812,14 @@ async function main() {
           // Create a new client for second clip to avoid event conflicts
           const creds = loadCredentials();
           const client2 = new SogniClientWrapper({
+            appSource: SOGNI_APP_SOURCE,
             network: openclawConfig?.defaultNetwork || 'fast',
             autoConnect: false,
-            ...(creds.SOGNI_API_KEY
-              ? { apiKey: creds.SOGNI_API_KEY, authType: 'apiKey' }
-              : {
-                  username: creds.SOGNI_USERNAME,
-                  password: creds.SOGNI_PASSWORD,
-                  authType: 'token'
-                })
+            apiKey: creds.SOGNI_API_KEY,
+            authType: 'apiKey'
           });
           await client2.connect();
+          await disableLiveModelAvailabilityEvents(client2);
 
           // Create second clip and wait for completion via events
           const clip2Promise = new Promise((resolve, reject) => {
@@ -4203,7 +5830,7 @@ async function main() {
             client2.on(ClientEvent.JOB_COMPLETED, async (data) => {
               try {
                 clearTimeout(timeout);
-                const clip2Url = data.videoUrl;
+                const clip2Url = data.resultUrl || data.videoUrl;
                 if (!clip2Url) {
                   reject(new Error('No video URL returned for second clip.'));
                   return;
@@ -4262,11 +5889,11 @@ async function main() {
       if (options.json) {
         const output = {
           success: true,
-          type: options.video ? 'video' : 'image',
+          type: options.music ? 'music' : options.video ? 'video' : 'image',
           prompt: options.prompt,
           model: options.model,
-          width: options.width,
-          height: options.height,
+          width: options.music ? null : options.width,
+          height: options.music ? null : options.height,
           seed: firstResult.seed ?? options.seed,
           seedStrategy: options.seedStrategy || null,
           seeds,
@@ -4289,6 +5916,23 @@ async function main() {
         if (options.loraStrengths.length > 0) {
           output.loraStrengths = options.loraStrengths;
         }
+        if (options.music) {
+          output.duration = options.duration;
+          output.bpm = options.musicBpm ?? null;
+          output.keyscale = options.musicKeyscale || null;
+          output.timesignature = options.musicTimesig || null;
+          output.language = options.musicLanguage || null;
+          output.composerMode = options.musicComposerMode;
+          if (options.musicPromptStrength !== null && options.musicPromptStrength !== undefined) {
+            output.promptStrength = options.musicPromptStrength;
+          }
+          if (options.musicCreativity !== null && options.musicCreativity !== undefined) {
+            output.creativity = options.musicCreativity;
+          }
+          if (options.musicShift !== null && options.musicShift !== undefined) {
+            output.shift = options.musicShift;
+          }
+        }
         if (options.video) {
           output.workflow = options.videoWorkflow;
           output.fps = options.fps;
@@ -4361,7 +6005,7 @@ async function main() {
   } catch (error) {
     // Token auto-fallback: if using auto mode and got insufficient balance, retry with the other token
     const isBalanceError = error.code === 'INSUFFICIENT_BALANCE' || /insufficient/i.test(error.message);
-    if (_isAutoToken && isBalanceError && options.tokenType === 'spark') {
+    if (_allowAutoTokenFallback && isBalanceError && options.tokenType === 'spark') {
       log('Insufficient SPARK balance — retrying with SOGNI tokens...');
       options.tokenType = 'sogni';
       try {