@tangle-network/tcloud 0.4.6 → 0.4.8

package/dist/cli.cjs

@@ -248,6 +248,7 @@ var PrivateRouter = class {
 
 // src/client.ts
 var ROTATING_MARKER = "__tcloudRotating";
+var DIRECT_CLI_BRIDGE_MARKER = "__tcloudDirectCliBridge";
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 var SDK_VERSION = "0.4.0";
 async function proxiedFetch(privacy, url, init, streaming) {
@@ -297,6 +298,43 @@ var DEFAULT_RETRY = {
 };
 var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_PLATFORM_URL = "https://id.tangle.tools";
+var PROTECTED_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "model",
+  "messages",
+  "temperature",
+  "max_tokens",
+  "maxTokens",
+  "stream",
+  "stop",
+  "top_p",
+  "topP",
+  "frequency_penalty",
+  "frequencyPenalty",
+  "presence_penalty",
+  "presencePenalty",
+  "response_format",
+  "responseFormat",
+  "tools",
+  "tool_choice",
+  "toolChoice",
+  "gateway",
+  "bridge",
+  "agent_profile",
+  "agentProfile",
+  "session_id",
+  "sessionId"
+]);
+function sanitizeProviderOptions(providerOptions) {
+  if (!providerOptions) return {};
+  for (const key of Object.keys(providerOptions)) {
+    if (PROTECTED_PROVIDER_OPTION_KEYS.has(key)) {
+      throw new Error(
+        `providerOptions cannot override protected chat field "${key}"; use the typed ChatOptions field instead`
+      );
+    }
+  }
+  return providerOptions;
+}
 var TCloudClient = class _TCloudClient {
   baseURL;
   platformURL;
@@ -337,13 +375,21 @@ var TCloudClient = class _TCloudClient {
    * const reply = await client.ask('explain X', 'claude-code/sonnet')
    * ```
    *
-   * For session-resumable agentic dispatches (file edits, multi-turn
-   * coding), use the router-mediated `tcloud.bridge({...})` API instead
-   * (or POST to cli-bridge directly with `session_id` in the body).
+   * For session-resumable agentic dispatches, use `client.bridge(...)` on
+   * the returned direct client. `resume` is serialized to cli-bridge's
+   * `session_id` body field and the model wire format stays
+   * `<harness>/<model>` without the router-only `bridge/` prefix.
    */
   static fromCliBridge(opts) {
     const baseURL = opts.url.replace(/\/+$/, "") + "/v1";
-    return new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
+    const client = new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
+    Object.defineProperty(client, DIRECT_CLI_BRIDGE_MARKER, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return client;
   }
   /**
    * Build a client that rotates which operator serves each call. Mirrors
@@ -355,7 +401,7 @@ var TCloudClient = class _TCloudClient {
    *
    * ```ts
    * const tcloud = TCloudClient.rotating({
-   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   apiKey: process.env.TANGLE_API_KEY,
    *   routing: { strategy: 'min-exposure' },
    * })
    * await tcloud.ask('hello')
@@ -396,7 +442,7 @@ var TCloudClient = class _TCloudClient {
   constructor(config = {}) {
     this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.platformURL = (config.platformURL || DEFAULT_PLATFORM_URL).replace(/\/$/, "");
-    this.apiKey = config.apiKey || process.env.TCLOUD_API_KEY;
+    this.apiKey = config.apiKey || process.env.TANGLE_API_KEY || process.env.TCLOUD_API_KEY;
     this.model = config.model || "gpt-4o-mini";
     this.privacy = config.privacy;
     this.limits = config.limits;
@@ -605,8 +651,8 @@ var TCloudClient = class _TCloudClient {
         delete headers["Authorization"];
       }
     }
-    if (bridge) {
-      headers["X-Bridge-Unlock"] = bridge.unlock;
+    if (bridge && !this._isDirectCliBridge()) {
+      headers["X-Bridge-Unlock"] = bridge.unlock ?? "";
       if (bridge.resume) headers["X-Resume"] = bridge.resume;
       if (bridge.bridgeUrl) headers["X-Bridge-Url"] = bridge.bridgeUrl;
       if (bridge.bridgeBearer) headers["X-Bridge-Bearer"] = bridge.bridgeBearer;
@@ -619,13 +665,24 @@ var TCloudClient = class _TCloudClient {
    */
   _effectiveModel(options) {
     if (options.bridge) {
+      if (this._isDirectCliBridge()) {
+        return options.bridge.model ? `${options.bridge.harness}/${options.bridge.model}` : options.bridge.harness;
+      }
       return options.bridge.model ? `bridge/${options.bridge.harness}/${options.bridge.model}` : `bridge/${options.bridge.harness}`;
     }
     return options.model || this.model;
   }
   /** Build the chat completions request body */
   _chatBody(options, stream) {
+    const providerOptions = sanitizeProviderOptions(options.providerOptions);
+    const sandboxBody = {};
+    if (options.sandbox?.agentProfile) sandboxBody.agent_profile = options.sandbox.agentProfile;
+    if (options.sandbox?.sessionId) sandboxBody.session_id = options.sandbox.sessionId;
+    if (this._isDirectCliBridge() && options.bridge?.resume && !sandboxBody.session_id) {
+      sandboxBody.session_id = options.bridge.resume;
+    }
     return JSON.stringify({
+      ...providerOptions,
       model: this._effectiveModel(options),
       messages: options.messages,
       temperature: options.temperature,
@@ -639,7 +696,7 @@ var TCloudClient = class _TCloudClient {
       tools: options.tools,
       tool_choice: options.toolChoice,
       ...options.gateway ? { gateway: options.gateway } : {},
-      ...options.providerOptions
+      ...sandboxBody
     });
   }
   /** Chat completion (non-streaming) */
@@ -720,7 +777,13 @@ var TCloudClient = class _TCloudClient {
         "TCloudClient.rotating() cannot dispatch sandbox-harness sessions.\nSandbox sessions bind to a single operator; rotation is meaningful only for\nstateless calls. Use TCloudClient.shielded() + AgentProfile.confidential.tee\nfor privacy-preserving sandbox execution instead."
       );
     }
-    return new BridgeSession(this, cfg);
+    if (!this._isDirectCliBridge() && cfg.unlock == null) {
+      throw new Error("Bridge unlock is required for router-mediated bridge sessions");
+    }
+    return new BridgeSession(this, cfg, this._isDirectCliBridge());
+  }
+  _isDirectCliBridge() {
+    return this[DIRECT_CLI_BRIDGE_MARKER] === true;
   }
   /**
    * Rotation stats — populated only on clients created via
@@ -886,6 +949,49 @@ var TCloudClient = class _TCloudClient {
       })
     });
   }
+  /**
+   * Edit / inpaint / variate an existing image with a text prompt.
+   * Sibling to `imageGenerate`; routes to `/v1/images/edits` via
+   * multipart/form-data per the OpenAI spec.
+   *
+   * Reference image attachments may be passed as `Blob`, `ArrayBuffer`,
+   * or `{data: base64, mediaType, filename?}`. Multi-image composition
+   * (e.g. gpt-image-2 with two reference frames + a prompt that fuses
+   * them) is supported by passing an array; for legacy models only the
+   * first image is honored upstream.
+   */
+  async imagesEdit(options) {
+    const formData = new FormData();
+    formData.append("prompt", options.prompt);
+    formData.append("model", options.model || "gpt-image-2");
+    if (options.n != null) formData.append("n", String(options.n));
+    if (options.size) formData.append("size", options.size);
+    if (options.quality) formData.append("quality", options.quality);
+    if (options.response_format) formData.append("response_format", options.response_format);
+    if (options.mask) formData.append("mask", toEditBlob(options.mask, "mask.png"), "mask.png");
+    const images = Array.isArray(options.image) ? options.image : [options.image];
+    if (images.length === 0) {
+      throw new TCloudError(400, "imagesEdit requires at least one image attachment");
+    }
+    images.forEach((img, idx) => {
+      const blob = toEditBlob(img, `image-${idx + 1}.png`);
+      formData.append("image[]", blob, blobFilename(img, `image-${idx + 1}.png`));
+    });
+    const headers = { ...this.headers };
+    delete headers["Content-Type"];
+    this.checkLimits();
+    const res = await proxiedFetch(this.privacy, `${this.baseURL}/images/edits`, {
+      method: "POST",
+      headers,
+      body: formData
+    }, false);
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: res.statusText }));
+      throw new TCloudError(res.status, err.error?.message || err.error || err.message || res.statusText);
+    }
+    this._requestCount++;
+    return res.json();
+  }
   /** Rerank documents by relevance to a query */
   async rerank(options) {
     return this._request(`${this.baseURL}/rerank`, {
@@ -977,7 +1083,7 @@ var TCloudClient = class _TCloudClient {
   }
   /** Get video generation status */
   async videoStatus(id) {
-    return this._fetch(`${this.baseURL}/video?id=${id}`);
+    return this._fetch(`${this.baseURL}/video/${encodeURIComponent(id)}`);
   }
   /** Generate an avatar video (lip-synced talking head from audio + face image).
    *  Returns 202 with a job_id for async polling via avatarJobStatus(). */
@@ -1237,12 +1343,14 @@ var ALL_TIERS = [
   { name: "max-gpu-tee", cpu: 64, ramGb: 256, gpu: 4, tee: true }
 ];
 var BridgeSession = class _BridgeSession {
-  constructor(client, cfg) {
+  constructor(client, cfg, direct = false) {
     this.client = client;
     this.cfg = cfg;
+    this.direct = direct;
   }
   client;
   cfg;
+  direct;
   /** Full chat completion (non-streaming). */
   async chat(options) {
     return this.client.chat({ ...options, bridge: this.cfg });
@@ -1276,15 +1384,16 @@ var BridgeSession = class _BridgeSession {
   }
   /** Clone with a new resume id — same harness, different logical conversation. */
   withResume(resume) {
-    return new _BridgeSession(this.client, { ...this.cfg, resume });
+    return new _BridgeSession(this.client, { ...this.cfg, resume }, this.direct);
   }
   /** Clone with a different model inside the same harness. */
   withModel(model) {
-    return new _BridgeSession(this.client, { ...this.cfg, model });
+    return new _BridgeSession(this.client, { ...this.cfg, model }, this.direct);
   }
   /** The effective model id that will land on the router (`bridge/<harness>/<model>`). */
   get model() {
-    return this.cfg.model ? `bridge/${this.cfg.harness}/${this.cfg.model}` : `bridge/${this.cfg.harness}`;
+    const prefix = this.direct ? "" : "bridge/";
+    return this.cfg.model ? `${prefix}${this.cfg.harness}/${this.cfg.model}` : `${prefix}${this.cfg.harness}`;
   }
   /** The resume id currently bound to this session, if any. */
   get resume() {
@@ -1306,6 +1415,32 @@ function selectTiers(all, n) {
 function formatPrice(pricePerToken) {
   return `$${(pricePerToken * 1e3).toFixed(6)}/1K tokens`;
 }
+function toEditBlob(input, defaultFilename) {
+  if (input instanceof Blob) return input;
+  if (input instanceof ArrayBuffer) return new Blob([input], { type: "image/png" });
+  const binary = base64ToUint8Array(input.data);
+  const copy = new Uint8Array(binary.byteLength);
+  copy.set(binary);
+  return new Blob([copy.buffer], { type: input.mediaType || "image/png" });
+  void defaultFilename;
+}
+function blobFilename(input, fallback) {
+  if (typeof input === "object" && !(input instanceof Blob) && !(input instanceof ArrayBuffer)) {
+    if (input.filename) return input.filename;
+  }
+  return fallback;
+}
+function base64ToUint8Array(b64) {
+  const m = /^data:[^;,]*(?:;[^,]*)?,(.+)$/.exec(b64);
+  const raw = m ? m[1] : b64;
+  const bin = typeof atob === "function" ? atob(raw) : (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.Buffer.from(raw, "base64").toString("binary")
+  );
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
 var TCloudError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -1704,7 +1839,14 @@ function buildSandboxCreateOptions(options) {
       memoryMB: options.memoryMb,
       diskGB: options.diskGb
     } : void 0,
-    backend: options.backend ? { type: options.backend } : void 0,
+    // backend: merge `backend` (type string) with `agentProfile` (carried
+    // as `backend.profile` on the underlying SDK). Either may be set
+    // independently; setting both produces `{ type, profile }`. Setting
+    // neither leaves `backend` undefined so the SDK applies its default.
+    backend: options.backend || options.agentProfile ? {
+      ...options.backend ? { type: options.backend } : {},
+      ...options.agentProfile ? { profile: options.agentProfile } : {}
+    } : void 0,
     confidential: options.tee ? {
       tee: options.tee,
       sealed: options.sealed || void 0,
@@ -1804,7 +1946,7 @@ var TCloud = class _TCloud extends TCloudClient {
    *
    * ```ts
    * const client = TCloud.rotating({
-   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   apiKey: process.env.TANGLE_API_KEY,
    *   routing: { strategy: 'min-exposure' },
    * })
    * const stats = client.getRotationStats()
@@ -1822,6 +1964,23 @@ var TCloud = class _TCloud extends TCloudClient {
    * ```
    */
   static generateWallet = generateWallet;
+  /**
+   * Create a Sandbox SDK client using this TCloud client's API key by default.
+   *
+   * ```ts
+   * const tcloud = new TCloud({ apiKey })
+   * const sandbox = await tcloud.sandbox().create({ name: 'runner' })
+   * ```
+   */
+  sandbox(config = {}) {
+    const apiKey = config.apiKey ?? this.apiKey;
+    if (!apiKey) throw new Error("TCloud.sandbox() requires an apiKey");
+    return new TCloudSandbox({ ...config, apiKey });
+  }
+  /** Create a standalone Sandbox SDK client. */
+  static sandbox(config) {
+    return new TCloudSandbox(config);
+  }
 };
 
 // src/cli.ts
@@ -1838,8 +1997,14 @@ function ensureDir() {
 }
 function loadConfig() {
   ensureDir();
-  if (fs.existsSync(CONFIG_FILE)) return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
-  return { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
+  const fileConfig = fs.existsSync(CONFIG_FILE) ? JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) : { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
+  return {
+    ...fileConfig,
+    ...process.env.TANGLE_ROUTER_URL ? { apiUrl: process.env.TANGLE_ROUTER_URL.replace(/\/v1\/?$/, "") } : {},
+    ...process.env.TCLOUD_API_URL ? { apiUrl: process.env.TCLOUD_API_URL.replace(/\/v1\/?$/, "") } : {},
+    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {},
+    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {}
+  };
 }
 function saveConfig(c) {
   ensureDir();
@@ -1895,6 +2060,15 @@ function packageVersion() {
   }
   return "0.0.0";
 }
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function firstImageResult(resp) {
+  return resp.data?.[0]?.url ?? resp.data?.[0]?.b64_json;
+}
+function videoResultUrl(resp) {
+  return resp.url ?? resp.video_url ?? resp.id;
+}
 var program = new import_commander.Command();
 program.name("tcloud").description("Tangle AI Cloud CLI").version(packageVersion());
 program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--sandbox-url <url>", "Sandbox API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
@@ -2156,6 +2330,111 @@ program.command("models").description("List available models").option("-s, --sea
     console.error("Error:", e.message);
   }
 });
+program.command("image-generate").description("Generate an image").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Image model").option("--size <size>", "Output size").option("--quality <quality>", "Output quality").option("-n, --count <n>", "Number of images").option("--response-format <format>", "url or b64_json").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.imageGenerate({
+      prompt: opts.prompt,
+      model: opts.model,
+      size: opts.size,
+      quality: opts.quality,
+      n: optionalNumber(opts.count),
+      response_format: opts.responseFormat
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    const result = firstImageResult(resp);
+    if (result) console.log(result);
+    else printJson(resp);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("video-generate").description("Generate a video").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Video model/provider").option("--provider <provider>", "Video provider, e.g. kling or runway").option("--duration <seconds>", "Duration in seconds").option("--resolution <resolution>", "Output resolution, e.g. 720p or 1080p").option("--aspect-ratio <ratio>", "Output aspect ratio, e.g. 16:9 or 9:16").option("--size <size>", "Exact output size, e.g. 1280x720").option("--image-url <url>", "Reference image URL").option("--generate-audio", "Generate audio when the model supports it").option("--seed <seed>", "Deterministic seed").option("--callback-url <url>", "Webhook callback URL").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.videoGenerate({
+      prompt: opts.prompt,
+      model: opts.model,
+      provider: opts.provider,
+      duration: optionalNumber(opts.duration),
+      resolution: opts.resolution,
+      aspect_ratio: opts.aspectRatio,
+      size: opts.size,
+      image_url: opts.imageUrl,
+      generate_audio: opts.generateAudio,
+      seed: optionalNumber(opts.seed),
+      callback_url: opts.callbackUrl
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    const result = videoResultUrl(resp);
+    if (result) console.log(result);
+    else printJson(resp);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("speech").description("Generate speech audio").requiredOption("-i, --input <text>", "Input text").option("-m, --model <model>", "Speech model").option("--voice <voice>", "Voice").option("-o, --output <file>", "Output file", "speech.mp3").option("--json", "Print JSON metadata").action(async (opts) => {
+  const client = getClient();
+  try {
+    const audio = await client.speech({
+      input: opts.input,
+      model: opts.model,
+      voice: opts.voice
+    });
+    fs.writeFileSync(opts.output, Buffer.from(audio));
+    const result = { output: opts.output, bytes: audio.byteLength };
+    if (opts.json) printJson(result);
+    else console.log(opts.output);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("transcribe").description("Transcribe an audio file").argument("<file>", "Audio file").option("-m, --model <model>", "Transcription model").option("--language <language>", "Language hint").option("--prompt <prompt>", "Prompt hint").option("--json", "Print raw JSON response").action(async (file, opts) => {
+  const client = getClient();
+  try {
+    const data = fs.readFileSync(file);
+    const blob = new Blob([data]);
+    const resp = await client.transcribe(blob, {
+      model: opts.model,
+      language: opts.language,
+      prompt: opts.prompt
+    });
+    if (opts.json) printJson(resp);
+    else console.log(resp.text);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("avatar-generate").description("Generate an avatar video").requiredOption("--audio-url <url>", "Narration audio URL").option("--image-url <url>", "Face image URL").option("--avatar-id <id>", "Preset avatar ID").option("--duration <seconds>", "Target duration in seconds").option("--output-format <format>", "Output format").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.avatarGenerate({
+      audio_url: opts.audioUrl,
+      image_url: opts.imageUrl,
+      avatar_id: opts.avatarId,
+      duration_seconds: optionalNumber(opts.duration),
+      output_format: opts.outputFormat
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    console.log(resp.result?.video_url ?? resp.job_id);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
 program.command("operators").description("List active operators").action(async () => {
   const client = getClient();
   try {

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   TCloud
-} from "./chunk-F6OVKJG3.js";
+} from "./chunk-27OTTDMZ.js";
 import {
   TCloudSandbox
-} from "./chunk-DBIT227N.js";
+} from "./chunk-DRCOPW7D.js";
 import {
   generateWallet
-} from "./chunk-4ZUVGKVH.js";
-import "./chunk-M5K3EFNP.js";
+} from "./chunk-YWN4JOCW.js";
+import "./chunk-CVWEKCQ3.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -24,8 +24,14 @@ function ensureDir() {
 }
 function loadConfig() {
   ensureDir();
-  if (fs.existsSync(CONFIG_FILE)) return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
-  return { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
+  const fileConfig = fs.existsSync(CONFIG_FILE) ? JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) : { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
+  return {
+    ...fileConfig,
+    ...process.env.TANGLE_ROUTER_URL ? { apiUrl: process.env.TANGLE_ROUTER_URL.replace(/\/v1\/?$/, "") } : {},
+    ...process.env.TCLOUD_API_URL ? { apiUrl: process.env.TCLOUD_API_URL.replace(/\/v1\/?$/, "") } : {},
+    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {},
+    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {}
+  };
 }
 function saveConfig(c) {
   ensureDir();
@@ -81,6 +87,15 @@ function packageVersion() {
   }
   return "0.0.0";
 }
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function firstImageResult(resp) {
+  return resp.data?.[0]?.url ?? resp.data?.[0]?.b64_json;
+}
+function videoResultUrl(resp) {
+  return resp.url ?? resp.video_url ?? resp.id;
+}
 var program = new Command();
 program.name("tcloud").description("Tangle AI Cloud CLI").version(packageVersion());
 program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--sandbox-url <url>", "Sandbox API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
@@ -342,6 +357,111 @@ program.command("models").description("List available models").option("-s, --sea
     console.error("Error:", e.message);
   }
 });
+program.command("image-generate").description("Generate an image").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Image model").option("--size <size>", "Output size").option("--quality <quality>", "Output quality").option("-n, --count <n>", "Number of images").option("--response-format <format>", "url or b64_json").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.imageGenerate({
+      prompt: opts.prompt,
+      model: opts.model,
+      size: opts.size,
+      quality: opts.quality,
+      n: optionalNumber(opts.count),
+      response_format: opts.responseFormat
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    const result = firstImageResult(resp);
+    if (result) console.log(result);
+    else printJson(resp);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("video-generate").description("Generate a video").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Video model/provider").option("--provider <provider>", "Video provider, e.g. kling or runway").option("--duration <seconds>", "Duration in seconds").option("--resolution <resolution>", "Output resolution, e.g. 720p or 1080p").option("--aspect-ratio <ratio>", "Output aspect ratio, e.g. 16:9 or 9:16").option("--size <size>", "Exact output size, e.g. 1280x720").option("--image-url <url>", "Reference image URL").option("--generate-audio", "Generate audio when the model supports it").option("--seed <seed>", "Deterministic seed").option("--callback-url <url>", "Webhook callback URL").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.videoGenerate({
+      prompt: opts.prompt,
+      model: opts.model,
+      provider: opts.provider,
+      duration: optionalNumber(opts.duration),
+      resolution: opts.resolution,
+      aspect_ratio: opts.aspectRatio,
+      size: opts.size,
+      image_url: opts.imageUrl,
+      generate_audio: opts.generateAudio,
+      seed: optionalNumber(opts.seed),
+      callback_url: opts.callbackUrl
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    const result = videoResultUrl(resp);
+    if (result) console.log(result);
+    else printJson(resp);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("speech").description("Generate speech audio").requiredOption("-i, --input <text>", "Input text").option("-m, --model <model>", "Speech model").option("--voice <voice>", "Voice").option("-o, --output <file>", "Output file", "speech.mp3").option("--json", "Print JSON metadata").action(async (opts) => {
+  const client = getClient();
+  try {
+    const audio = await client.speech({
+      input: opts.input,
+      model: opts.model,
+      voice: opts.voice
+    });
+    fs.writeFileSync(opts.output, Buffer.from(audio));
+    const result = { output: opts.output, bytes: audio.byteLength };
+    if (opts.json) printJson(result);
+    else console.log(opts.output);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("transcribe").description("Transcribe an audio file").argument("<file>", "Audio file").option("-m, --model <model>", "Transcription model").option("--language <language>", "Language hint").option("--prompt <prompt>", "Prompt hint").option("--json", "Print raw JSON response").action(async (file, opts) => {
+  const client = getClient();
+  try {
+    const data = fs.readFileSync(file);
+    const blob = new Blob([data]);
+    const resp = await client.transcribe(blob, {
+      model: opts.model,
+      language: opts.language,
+      prompt: opts.prompt
+    });
+    if (opts.json) printJson(resp);
+    else console.log(resp.text);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
+program.command("avatar-generate").description("Generate an avatar video").requiredOption("--audio-url <url>", "Narration audio URL").option("--image-url <url>", "Face image URL").option("--avatar-id <id>", "Preset avatar ID").option("--duration <seconds>", "Target duration in seconds").option("--output-format <format>", "Output format").option("--json", "Print raw JSON response").action(async (opts) => {
+  const client = getClient();
+  try {
+    const resp = await client.avatarGenerate({
+      audio_url: opts.audioUrl,
+      image_url: opts.imageUrl,
+      avatar_id: opts.avatarId,
+      duration_seconds: optionalNumber(opts.duration),
+      output_format: opts.outputFormat
+    });
+    if (opts.json) {
+      printJson(resp);
+      return;
+    }
+    console.log(resp.result?.video_url ?? resp.job_id);
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
 program.command("operators").description("List active operators").action(async () => {
   const client = getClient();
   try {