focalapi-cli 0.1.0 → 0.1.1

package/README.md

@@ -2,13 +2,13 @@
 
 # focalapi-cli
 
-**给你的 AI Agent 赋予 focalapi 的全部模型能力**
+**给你的 AI Agent 赋予 focalapi 的创作模型能力**
 
 [![npm](https://img.shields.io/npm/v/focalapi-cli?color=brightgreen&label=npm)](https://www.npmjs.com/package/focalapi-cli)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-focalapi 的对话、图像生成、视频生成、联网搜索、音频、向量、Rerank、用量查询能力，都可以通过 focalapi CLI + Skills 交给 Claude Code、Codex、OpenCode、Hermes 等本地 Agent 调用。
+focalapi 的图像、视频、音频与视觉创作能力，可以通过 focalapi CLI + Skills 交给本地 Agent 调用；DeepSeek 仅作为提示词、分镜和轻量文本的备用能力。
 
 ```shell
 npm i -g focalapi-cli
@@ -22,11 +22,9 @@ npm i -g focalapi-cli
 
 让你的 AI Agent 具备这些 focalapi 能力，并能在复杂任务中组合调用：
 
-- **模型调用**：文本对话、多模态输入（图片理解）、流式输出、管道输入
-- **图片 / 视频生成**：文生图、文生视频，产物自动下载到本地；视频任务支持异步编排
-- **联网搜索**：`/v1/alpha/search`，给 Agent 接上实时信息
+- **图片 / 视频生成**：文生图、图生图、文生视频，产物自动下载到本地；视频任务支持异步编排
 - **音频**：语音转写（transcribe）、文字转语音（speech）
-- **向量 / 重排**：embeddings 与 rerank，检索链路两件套
+- **DeepSeek 文本辅助**：提示词、分镜、旁白和轻量脚本草稿
 - **Agent 接入**：`focalapi connect` 把内置 Skills 装进本机 Agent，Agent 即刻学会调用 focalapi
 - **治理闭环**：`usage` 额度用量、`doctor` 只读诊断（用免费演练模型做端到端自检，不花额度）
 
@@ -40,7 +38,7 @@ focalapi-cli 不是让你记住更多命令，而是把 focalapi 的模型能力
 
 调用链路（Agent 视角）:
 models list 选模型
-  -> chat / gen / search / embed / rerank 调用
+  -> gen / audio / chat（DeepSeek 备用）调用
   -> 产物落盘（图像/视频/音频）
   -> usage 看额度，doctor 做诊断
 ```
@@ -71,34 +69,57 @@ export FOCALAPI_API_KEY=sk-xxxx
 
 ## 常用任务
 
-### 对话与多模态
+### DeepSeek 文本辅助
 
 ```shell
-focalapi chat "用一句话总结 RAG 的核心思想" -m focal-rehearsal-chat
+focalapi chat "把这个产品简介写成 6 镜头分镜" -m <DeepSeek模型>
 
-cat report.md | focalapi chat -m <model> --system "你是严谨的技术编辑"
+cat brief.md | focalapi chat -m <DeepSeek模型> --system "你是专业的广告分镜师"
 
-focalapi chat "描述这张图片" -m <多模态模型> --input @photo.jpg
+focalapi chat "提炼这张参考图的构图和色彩" -m <DeepSeek模型> --input @photo.jpg
 ```
 
 ### 生成图片 / 视频
 
 ```shell
+# 先读取模型的端点、支持参数、默认值与范围；适合 Agent 在生成前自检
+focalapi models get doubao-seedream-4-5-251128
+focalapi models get doubao-seedance-2-0-260128 --json
+
 focalapi gen image "未来城市海报" -m <图像模型> --size 1024x1024 -o ./out
+focalapi gen image "产品主视觉" -m gpt-image-2 --size 1536x1024 --quality high --background opaque -o ./out
+focalapi gen image "将背景改为雨夜" -m gpt-image-2 --image https://example.com/source.png \
+  --mask https://example.com/mask.png --response-format b64_json -o ./out
+# OpenAI 图像模型可选持久任务：立即获得 task_id，稍后查询 data[].url
+focalapi gen image "产品主视觉" -m gpt-image-2 --size 1024x1024 --no-wait --json
+focalapi task status <task_id> --json
+
+# Gemini 图像模型是原生 Gemini 端点，不走 OpenAI 图像端点
+focalapi gen gemini-image "一只水彩风格的橘猫" -m gemini-3.1-flash-image-preview \
+  --aspect-ratio 16:9 --image-size 2K -o ./out
+# Gemini native generationConfig fields can be passed through --config; named flags cover --image, --system, --seed, --thinking-level, --temperature, and --top-p. responseFormat.image and a single candidate are fixed.
 
 # 视频：默认等待完成并下载；异步编排用 --no-wait
 focalapi gen video "海浪拍打礁石" -m <视频模型> --seconds 5
+focalapi gen video "海浪拍打礁石" -m doubao-seedance-2-0-260128 \
+  --seconds 5 --resolution 720p --ratio 16:9 --generate-audio true --no-wait --json
+focalapi gen video "让海浪缓慢推进" -m doubao-seedance-2-0-260128 \
+  --image https://example.com/frame.png --generate-audio false --watermark true \
+  --return-last-frame true --callback-url https://example.com/callback \
+  --execution-expires-after 7200 --safety-identifier customer-42 --priority 4 --no-wait --json
+# Ark-compatible content (text, image_url, video_url, audio_url with roles) is available unchanged through metadata.content:
+focalapi gen video "ignored when content is supplied" -m doubao-seedance-2-0-260128 \
+  --content '[{"type":"text","text":"A cinematic ocean wave."}]' --no-wait --json
 focalapi gen video "海浪拍打礁石" -m <视频模型> --no-wait --json   # 拿 task_id
 focalapi task status <task_id> --json
 focalapi task download <task_id> -o ./out
 ```
 
-### 搜索 / 向量 / 重排 / 音频
+`models get` 是生成前的权威检查入口：返回 `supported_endpoint_types`、`supported_params`，并在可用时提供官方文档链接。CLI 会在本地拒绝已知的不支持参数，例如 Seedream 4.5 的低于 3.69 MP 的尺寸、Seedance Fast/Mini 的 1080p、或 Seedance 的非 4–15 秒时长；不会把这些确定会失败的请求交给上游。同步图像生成时，等待进度输出到 stderr，因此 `--json` 的 stdout 始终保持为可解析 JSON。
+
+### 音频创作
 
 ```shell
-focalapi search "过去7天 AI 行业新闻" -m <搜索模型> --json
-focalapi embed "待编码文本" -m <向量模型> --json
-focalapi rerank -m <rerank模型> --query "问题" --docs @docs.json
 focalapi audio transcribe meeting.mp3 -m <转写模型>
 focalapi audio speech "大家好" -m <TTS模型> -o hello.mp3
 ```
@@ -114,9 +135,9 @@ focalapi doctor         # 全链路只读诊断，任何调用失败先跑它
 ## Agent 接入（connect）
 
 ```shell
-focalapi connect list                 # 探测本机 Agent（Claude Code / Codex / OpenCode / Hermes）
+focalapi connect list                 # 探测本机已支持的 Agent
 focalapi connect install              # 向全部检测到的 Agent 安装 skills
-focalapi connect install claude-code  # 只装指定 Agent
+focalapi connect install <agent-id>   # 只装指定 Agent
 focalapi connect uninstall            # 按 manifest 精确卸载，不碰其他文件
 ```
 
@@ -134,12 +155,10 @@ focalapi connect uninstall            # 按 manifest 精确卸载，不碰其他
 | 任务 | 命令 |
 |---|---|
 | 登录 / 状态 / 登出 | `focalapi auth login / status / logout` |
-| 对话和多模态推理 | `focalapi chat` |
+| DeepSeek 文本辅助 | `focalapi chat` |
 | 图片 / 视频生成 | `focalapi gen image / gen video` |
-| 任务查询与产物下载 | `focalapi task status / download` |
-| 联网搜索 | `focalapi search` |
+| 任务查询与产物下载 | `focalapi task status / download`（图像任务使用 status 读取 `data[].url`） |
 | 语音转写 / 合成 | `focalapi audio transcribe / speech` |
-| 向量化 / 重排序 | `focalapi embed / rerank` |
 | 模型查询 | `focalapi models list / get` |
 | 额度用量 | `focalapi usage` |
 | 诊断排障 | `focalapi doctor` |

package/dist/cli.js

@@ -8,6 +8,10 @@ var ApiError = class extends Error {
   code;
   status;
   hint;
+  /** 上游返回的稳定错误代码或类型；不包含密钥等敏感请求信息。 */
+  upstreamCode;
+  /** 可用于向服务方关联日志的请求 ID。 */
+  requestId;
   /** 上游原始响应体（已截断），仅调试用途，打印前需脱敏。 */
   body;
   constructor(code, message, opts) {
@@ -17,6 +21,8 @@ var ApiError = class extends Error {
     this.status = opts?.status;
     this.hint = opts?.hint;
     this.body = opts?.body;
+    this.upstreamCode = opts?.upstreamCode;
+    this.requestId = opts?.requestId;
   }
   toJSON() {
     return {
@@ -24,12 +30,14 @@ var ApiError = class extends Error {
         code: this.code,
         message: this.message,
         ...this.hint ? { hint: this.hint } : {},
-        ...this.status !== void 0 ? { status: this.status } : {}
+        ...this.status !== void 0 ? { status: this.status } : {},
+        ...this.upstreamCode ? { upstream_code: this.upstreamCode } : {},
+        ...this.requestId ? { request_id: this.requestId } : {}
       }
     };
   }
 };
-function refineErrorCode(status, message) {
+function refineErrorCode(status, message, opts) {
   const m = message.toLowerCase();
   if (m.includes("quota") || m.includes("\u989D\u5EA6") || m.includes("insufficient")) {
     return "insufficient_quota";
@@ -38,14 +46,17 @@ function refineErrorCode(status, message) {
     return "model_not_found";
   }
   if (m.includes("key") || m.includes("token") || m.includes("auth")) {
-    return status === 401 || status === 403 ? "invalid_api_key" : "invalid_request";
+    if (status === 401 || status === 403) {
+      return opts?.authFailureIsInvalidApiKey ? "invalid_api_key" : "upstream_auth_failed";
+    }
+    return "invalid_request";
   }
   switch (status) {
     case 400:
       return "invalid_request";
     case 401:
     case 403:
-      return "invalid_api_key";
+      return opts?.authFailureIsInvalidApiKey ? "invalid_api_key" : "authentication_failed";
     case 404:
       return "model_not_found";
     case 429:
@@ -103,6 +114,14 @@ function printError(err, opts) {
       const hint = err.hint;
       if (hint) {
         process.stderr.write(`\u63D0\u793A\uFF1A${hint}
+`);
+      }
+      if (err.upstreamCode) {
+        process.stderr.write(`\u4E0A\u6E38\u4EE3\u7801\uFF1A${err.upstreamCode}
+`);
+      }
+      if (err.requestId) {
+        process.stderr.write(`\u8BF7\u6C42 ID\uFF1A${err.requestId}
 `);
       }
     }
@@ -136,7 +155,7 @@ function displayWidth(s) {
 }
 
 // src/lib/version.ts
-var VERSION = true ? "0.1.0" : "0.0.0-dev";
+var VERSION = true ? "0.1.1" : "0.0.0-dev";
 
 // src/commands/auth.ts
 import { createInterface } from "readline/promises";
@@ -248,7 +267,8 @@ function extractErrorMessage(raw) {
   const obj = parsed;
   const errObj = obj?.error;
   const message = typeof errObj?.message === "string" && errObj.message || typeof obj?.message === "string" && obj.message || JSON.stringify(parsed).slice(0, 500);
-  return { message, body: parsed };
+  const upstreamCode = [errObj?.code, errObj?.type, obj?.code, obj?.type].find((value) => typeof value === "string");
+  return { message, body: parsed, upstreamCode: typeof upstreamCode === "string" ? upstreamCode : void 0 };
 }
 async function request(opts) {
   const res = await rawRequest(opts);
@@ -298,9 +318,10 @@ async function rawRequest(opts) {
   }
   if (!res.ok) {
     const text = await res.text().catch(() => "");
-    const { message, body } = extractErrorMessage(text);
-    const code = refineErrorCode(res.status, message);
-    throw new ApiError(code, message, { status: res.status, body });
+    const { message, body, upstreamCode } = extractErrorMessage(text);
+    const code = refineErrorCode(res.status, message, { authFailureIsInvalidApiKey: opts.authFailureIsInvalidApiKey });
+    const requestId = res.headers.get("x-request-id") ?? res.headers.get("request-id") ?? res.headers.get("x-requestid") ?? void 0;
+    throw new ApiError(code, message, { status: res.status, body, upstreamCode, requestId });
   }
   return res;
 }
@@ -342,7 +363,8 @@ async function fetchTokenUsage(baseUrl, apiKey) {
     baseUrl,
     path: "/api/usage/token/",
     apiKey,
-    timeoutMs: 15e3
+    timeoutMs: 15e3,
+    authFailureIsInvalidApiKey: true
   });
   if (!res.data) {
     throw new ApiError("bad_response", "\u7528\u91CF\u63A5\u53E3\u54CD\u5E94\u7F3A\u5C11 data \u5B57\u6BB5");
@@ -444,6 +466,39 @@ function registerAuth(program) {
 }
 
 // src/commands/models.ts
+function textValue(value) {
+  if (value === null || value === void 0 || value === "") return "-";
+  if (Array.isArray(value)) return value.length === 0 ? "-" : value.map(textValue).join(", ");
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+function parameterConstraint(parameter) {
+  const constraints = [];
+  if (parameter.required) constraints.push("\u5FC5\u586B");
+  if (parameter.default !== void 0) constraints.push(`\u9ED8\u8BA4 ${String(parameter.default)}`);
+  if (parameter.values?.length) constraints.push(`\u53EF\u9009 ${parameter.values.join(" / ")}`);
+  if (parameter.minimum !== void 0 || parameter.maximum !== void 0) {
+    constraints.push(`${parameter.minimum ?? "-\u221E"}\u2013${parameter.maximum ?? "\u221E"}`);
+  }
+  return [parameter.type, ...constraints, parameter.description].join("\uFF1B");
+}
+function printModelDetails(model) {
+  const { supported_params: supportedParams, ...summary } = model;
+  printTable(
+    ["\u5B57\u6BB5", "\u503C"],
+    Object.entries(summary).map(([key, value]) => [key, textValue(value)])
+  );
+  if (Array.isArray(supportedParams) && supportedParams.length > 0) {
+    process.stdout.write("\n\u652F\u6301\u53C2\u6570\n");
+    printTable(
+      ["\u53C2\u6570", "\u7EA6\u675F"],
+      supportedParams.map((parameter) => {
+        const item = parameter;
+        return [item.name, parameterConstraint(item)];
+      })
+    );
+  }
+}
 function registerModels(program) {
   const models = program.command("models").description("\u53EF\u7528\u6A21\u578B\u67E5\u8BE2");
   models.command("list").description("\u5217\u51FA\u5F53\u524D Key \u53EF\u7528\u7684\u5168\u90E8\u6A21\u578B").option("--filter <keyword>", "\u6309 id \u5173\u952E\u5B57\u8FC7\u6EE4\uFF08\u4E0D\u533A\u5206\u5927\u5C0F\u5199\uFF09").action(async (opts, cmd) => {
@@ -459,8 +514,8 @@ function registerModels(program) {
       printJson({ data: list });
     } else {
       printTable(
-        ["\u6A21\u578B ID", "\u63D0\u4F9B\u65B9"],
-        list.map((m) => [m.id, m.owned_by ?? "-"])
+        ["\u6A21\u578B ID", "\u63D0\u4F9B\u65B9", "\u652F\u6301\u7AEF\u70B9"],
+        list.map((m) => [m.id, m.owned_by ?? "-", textValue(m.supported_endpoint_types)])
       );
     }
   });
@@ -475,10 +530,7 @@ function registerModels(program) {
     if (g.json) {
       printJson(res);
     } else {
-      printTable(
-        ["\u5B57\u6BB5", "\u503C"],
-        Object.entries(res).map(([k, v]) => [k, typeof v === "object" ? JSON.stringify(v) : String(v)])
-      );
+      printModelDetails(res);
     }
   });
 }
@@ -551,7 +603,7 @@ function extractText(content) {
   return "";
 }
 function registerChat(program) {
-  program.command("chat").description("\u5BF9\u8BDD\u4E0E\u591A\u6A21\u6001\u63A8\u7406\uFF08/v1/chat/completions\uFF09").argument("[prompt...]", "\u63D0\u793A\u8BCD\uFF1B\u7701\u7565\u4E14 stdin \u4E3A\u7BA1\u9053\u65F6\u4ECE stdin \u8BFB\u53D6").option("-m, --model <model>", "\u6A21\u578B ID\uFF08\u6216\u8BBE FOCALAPI_MODEL\uFF09").option("--system <text>", "system \u63D0\u793A\u8BCD").option("--input <file...>", "\u8F93\u5165\u6587\u4EF6\uFF08\u56FE\u7247\u8F6C data URL\uFF0C\u5982 --input @photo.jpg\uFF1B@ \u524D\u7F00\u53EF\u9009\uFF09").option("--max-tokens <n>", "max_tokens", (v) => Number.parseInt(v, 10)).option("--stream", "\u5F3A\u5236\u6D41\u5F0F\u8F93\u51FA").option("--no-stream", "\u5F3A\u5236\u975E\u6D41\u5F0F").action(
+  program.command("chat").description("DeepSeek \u5907\u7528\u5BF9\u8BDD\u4E0E\u63D0\u793A\u8BCD\u8F85\u52A9\uFF08/v1/chat/completions\uFF09").argument("[prompt...]", "\u63D0\u793A\u8BCD\uFF1B\u7701\u7565\u4E14 stdin \u4E3A\u7BA1\u9053\u65F6\u4ECE stdin \u8BFB\u53D6").option("-m, --model <model>", "\u6A21\u578B ID\uFF08\u6216\u8BBE FOCALAPI_MODEL\uFF09").option("--system <text>", "system \u63D0\u793A\u8BCD").option("--input <file...>", "\u8F93\u5165\u6587\u4EF6\uFF08\u56FE\u7247\u8F6C data URL\uFF0C\u5982 --input @photo.jpg\uFF1B@ \u524D\u7F00\u53EF\u9009\uFF09").option("--max-tokens <n>", "max_tokens", (v) => Number.parseInt(v, 10)).option("--stream", "\u5F3A\u5236\u6D41\u5F0F\u8F93\u51FA").option("--no-stream", "\u5F3A\u5236\u975E\u6D41\u5F0F").action(
     async (promptParts, opts, cmd) => {
       const g = cmd.optsWithGlobals();
       const auth = resolveAuth(g);
@@ -724,6 +776,187 @@ import { join as join3, resolve as resolve2 } from "path";
 import { pipeline as pipeline2 } from "stream/promises";
 import { Readable as Readable2 } from "stream";
 
+// src/lib/model-capabilities.ts
+var IMAGE_CONSTRAINTS = {
+  "gpt-image-2": {
+    defaultSize: "1024x1024",
+    maxN: 8,
+    maxReferenceImages: 16,
+    minMegapixels: 0.65536,
+    maxMegapixels: 8.2944,
+    minEdge: 1024,
+    maxEdge: 3840,
+    edgeMultiple: 16,
+    maxAspectRatio: 3,
+    qualities: ["low", "medium", "high"],
+    backgrounds: ["auto", "opaque"]
+  },
+  "doubao-seedream-4-5-251128": {
+    defaultSize: "2048x2048",
+    maxN: 10,
+    maxReferenceImages: 10,
+    maxTotalImages: 15,
+    minMegapixels: 3.6864,
+    maxMegapixels: 16.777216
+  },
+  "doubao-seedream-5-0-pro-260628": {
+    defaultSize: "1024x1024",
+    maxN: 1,
+    maxReferenceImages: 10,
+    minMegapixels: 0.92,
+    maxMegapixels: 4.194304
+  },
+  "doubao-seedream-5-0-lite-260128": {
+    defaultSize: "2048x2048",
+    maxN: 14,
+    maxReferenceImages: 14,
+    maxTotalImages: 15,
+    minMegapixels: 3.6864,
+    maxMegapixels: 16.777216
+  },
+  "grok-imagine-image-quality": { defaultSize: "1024x1024", maxN: 10, maxReferenceImages: 3 },
+  "grok-imagine-image": { defaultSize: "1024x1024", maxN: 10, maxReferenceImages: 3 },
+  "grok-imagine-image-pro": { defaultSize: "1024x1024", maxN: 10, maxReferenceImages: 1 }
+};
+var SEEDANCE_RATIOS = ["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"];
+var VIDEO_CONSTRAINTS = {
+  "doubao-seedance-2-0-260128": {
+    resolutions: ["480p", "720p", "1080p", "4k"],
+    ratios: SEEDANCE_RATIOS,
+    minSeconds: 4,
+    maxSeconds: 15
+  },
+  "doubao-seedance-2-0-fast-260128": {
+    resolutions: ["480p", "720p"],
+    ratios: SEEDANCE_RATIOS,
+    minSeconds: 4,
+    maxSeconds: 15
+  },
+  "doubao-seedance-2-0-mini-260615": {
+    resolutions: ["480p", "720p"],
+    ratios: SEEDANCE_RATIOS,
+    minSeconds: 4,
+    maxSeconds: 15
+  }
+};
+var COMMON_GEMINI_RATIOS = ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+var GEMINI_IMAGE_CONSTRAINTS = {
+  "gemini-3-pro-image-preview": { aspectRatios: COMMON_GEMINI_RATIOS, imageSizes: ["1K", "2K", "4K"], supportsSampling: false },
+  "gemini-3.1-flash-image-preview": { aspectRatios: COMMON_GEMINI_RATIOS, imageSizes: ["1K", "2K", "4K"], supportsSampling: false },
+  "gemini-3.1-flash-lite-image-preview": {
+    aspectRatios: [...COMMON_GEMINI_RATIOS, "1:4", "4:1", "1:8", "8:1"],
+    imageSizes: ["1K"],
+    supportsSampling: true
+  }
+};
+function parseSize(size, model) {
+  const match = /^(\d+)x(\d+)$/i.exec(size.trim());
+  if (!match) {
+    throw new ApiError("invalid_request", `${model} size must be WIDTHxHEIGHT (received: ${size})`);
+  }
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+function megapixels(width, height) {
+  return width * height / 1e6;
+}
+function formatMegapixels(value) {
+  return value.toFixed(2).replace(/\.00$/, "");
+}
+function validateImageGeneration(model, input) {
+  if (input.responseFormat && input.responseFormat !== "url" && input.responseFormat !== "b64_json") {
+    throw new ApiError("invalid_request", `response_format must be url or b64_json (received: ${input.responseFormat})`);
+  }
+  const constraint = IMAGE_CONSTRAINTS[model.trim()];
+  if (!constraint) return;
+  if (input.n < 1 || input.n > constraint.maxN) {
+    throw new ApiError("invalid_request", `${model} n must be 1-${constraint.maxN} (received: ${input.n})`);
+  }
+  if (input.imageCount !== void 0 && constraint.maxReferenceImages !== void 0 && input.imageCount > constraint.maxReferenceImages) {
+    throw new ApiError("invalid_request", `${model} supports at most ${constraint.maxReferenceImages} reference images`);
+  }
+  if (input.imageCount !== void 0 && constraint.maxTotalImages !== void 0 && input.imageCount + input.n > constraint.maxTotalImages) {
+    throw new ApiError("invalid_request", `${model} supports at most ${constraint.maxTotalImages} input plus generated images`);
+  }
+  if (input.hasMask && model === "gpt-image-2" && input.imageCount !== 1) {
+    throw new ApiError("invalid_request", "gpt-image-2 mask requires exactly one reference image");
+  }
+  if (input.quality && constraint.qualities && !constraint.qualities.includes(input.quality.toLowerCase())) {
+    throw new ApiError("invalid_request", `${model} quality must be one of ${constraint.qualities.join(", ")} (received: ${input.quality})`);
+  }
+  if (input.background && constraint.backgrounds && !constraint.backgrounds.includes(input.background.toLowerCase())) {
+    throw new ApiError("invalid_request", `${model} background must be one of ${constraint.backgrounds.join(", ")} (received: ${input.background})`);
+  }
+  const { width, height } = parseSize(input.size ?? constraint.defaultSize, model);
+  const pixels = megapixels(width, height);
+  if (constraint.minEdge && (width < constraint.minEdge || height < constraint.minEdge) || constraint.maxEdge && (width > constraint.maxEdge || height > constraint.maxEdge) || constraint.edgeMultiple && (width % constraint.edgeMultiple !== 0 || height % constraint.edgeMultiple !== 0) || constraint.minMegapixels && pixels < constraint.minMegapixels || constraint.maxMegapixels && pixels > constraint.maxMegapixels) {
+    const edge = constraint.minEdge && constraint.maxEdge ? `${constraint.minEdge}-${constraint.maxEdge}px per edge` : "";
+    const step = constraint.edgeMultiple ? `, edge multiples of ${constraint.edgeMultiple}` : "";
+    const mp = constraint.minMegapixels && constraint.maxMegapixels ? `, ${formatMegapixels(constraint.minMegapixels)}-${formatMegapixels(constraint.maxMegapixels)} MP` : "";
+    throw new ApiError("invalid_request", `${model} does not support size=${width}x${height}; supported: ${edge}${step}${mp}`);
+  }
+  if (constraint.maxAspectRatio) {
+    const ratio = Math.max(width, height) / Math.min(width, height);
+    if (ratio > constraint.maxAspectRatio) {
+      throw new ApiError("invalid_request", `${model} longest-to-shortest edge ratio must not exceed ${constraint.maxAspectRatio}:1 (received: ${width}x${height})`);
+    }
+  }
+}
+function validateGeminiImageGeneration(model, input) {
+  const constraint = GEMINI_IMAGE_CONSTRAINTS[model.trim()];
+  if (!constraint) {
+    throw new ApiError("invalid_request", `${model} is not a supported Gemini image model; run focalapi models get ${model} first`);
+  }
+  if (input.aspectRatio && !constraint.aspectRatios.includes(input.aspectRatio)) {
+    throw new ApiError("invalid_request", `${model} aspectRatio must be one of ${constraint.aspectRatios.join(", ")} (received: ${input.aspectRatio})`);
+  }
+  if (input.imageSize && !constraint.imageSizes.includes(input.imageSize.toUpperCase())) {
+    throw new ApiError("invalid_request", `${model} imageSize must be one of ${constraint.imageSizes.join(", ")} (received: ${input.imageSize})`);
+  }
+  if (input.seed !== void 0 && (!Number.isInteger(input.seed) || input.seed < 0)) {
+    throw new ApiError("invalid_request", "seed must be a non-negative integer");
+  }
+  if (!constraint.supportsSampling && (input.thinkingLevel || input.temperature !== void 0 || input.topP !== void 0)) {
+    throw new ApiError("invalid_request", `${model} supports thinkingLevel, temperature, and topP only on gemini-3.1-flash-lite-image-preview`);
+  }
+  if (input.thinkingLevel && !["MINIMAL", "HIGH"].includes(input.thinkingLevel.toUpperCase())) {
+    throw new ApiError("invalid_request", "thinkingLevel must be MINIMAL or HIGH");
+  }
+  if (input.temperature !== void 0 && (!Number.isFinite(input.temperature) || input.temperature < 0 || input.temperature > 2)) {
+    throw new ApiError("invalid_request", "temperature must be between 0 and 2");
+  }
+  if (input.topP !== void 0 && (!Number.isFinite(input.topP) || input.topP < 0 || input.topP > 1)) {
+    throw new ApiError("invalid_request", "topP must be between 0 and 1");
+  }
+}
+function validateVideoGeneration(model, input) {
+  const constraint = VIDEO_CONSTRAINTS[model.trim()];
+  if (!constraint) return;
+  if (input.seconds !== void 0 && (input.seconds < constraint.minSeconds || input.seconds > constraint.maxSeconds)) {
+    throw new ApiError("invalid_request", `${model} seconds must be ${constraint.minSeconds}-${constraint.maxSeconds} (received: ${input.seconds})`);
+  }
+  if (input.resolution && !constraint.resolutions.includes(input.resolution.toLowerCase())) {
+    throw new ApiError("invalid_request", `${model} resolution must be one of ${constraint.resolutions.join(", ")} (received: ${input.resolution})`);
+  }
+  if (input.ratio && !constraint.ratios.includes(input.ratio)) {
+    throw new ApiError("invalid_request", `${model} ratio must be one of ${constraint.ratios.join(", ")} (received: ${input.ratio})`);
+  }
+  if (input.priority !== void 0 && model !== "doubao-seedance-2-0-260128") {
+    throw new ApiError("invalid_request", `${model} does not support priority; only doubao-seedance-2-0-260128 does`);
+  }
+  if (input.priority !== void 0 && (input.priority < 0 || input.priority > 9)) {
+    throw new ApiError("invalid_request", `${model} priority must be 0-9 (received: ${input.priority})`);
+  }
+  if (input.serviceTier && input.serviceTier !== "default") {
+    throw new ApiError("invalid_request", `${model} service_tier must be default (received: ${input.serviceTier})`);
+  }
+  if (input.executionExpiresAfter !== void 0 && (input.executionExpiresAfter < 3600 || input.executionExpiresAfter > 259200)) {
+    throw new ApiError("invalid_request", `${model} execution_expires_after must be 3600-259200 (received: ${input.executionExpiresAfter})`);
+  }
+  if (input.safetyIdentifier !== void 0 && !/^[\x21-\x7e]{1,64}$/.test(input.safetyIdentifier)) {
+    throw new ApiError("invalid_request", `${model} safety_identifier must contain 1-64 printable ASCII characters`);
+  }
+}
+
 // src/lib/tasks.ts
 import { createWriteStream } from "fs";
 import { mkdir } from "fs/promises";
@@ -767,11 +1000,21 @@ function extractProgress(body) {
   return void 0;
 }
 async function fetchTask(baseUrl, apiKey, taskId) {
-  const raw = await request({
-    baseUrl,
-    path: `/v1/video/generations/${encodeURIComponent(taskId)}`,
-    apiKey
-  });
+  let raw;
+  try {
+    raw = await request({
+      baseUrl,
+      path: `/v1/video/generations/${encodeURIComponent(taskId)}`,
+      apiKey
+    });
+  } catch (err) {
+    if (!(err instanceof ApiError) || err.status !== 404) throw err;
+    raw = await request({
+      baseUrl,
+      path: `/v1/images/generations/${encodeURIComponent(taskId)}`,
+      apiKey
+    });
+  }
   const obj = raw;
   const rawStatus = String(obj?.status ?? obj?.data?.status ?? "");
   return {
@@ -843,9 +1086,34 @@ function clampInt(value, min, max, name) {
   }
   return value;
 }
+function parseBooleanOption(value, name) {
+  switch (value.trim().toLowerCase()) {
+    case "true":
+      return true;
+    case "false":
+      return false;
+    default:
+      throw new ApiError("invalid_request", `--${name} must be true or false (received: ${value})`);
+  }
+}
+async function withProgress(label, operation) {
+  const startedAt = Date.now();
+  info(`${label}\u2026`);
+  const timer = setInterval(() => {
+    const elapsedSeconds = Math.max(1, Math.floor((Date.now() - startedAt) / 1e3));
+    info(`${label}\uFF0C\u5DF2\u7B49\u5F85 ${elapsedSeconds} \u79D2\u2026`);
+  }, 1e4);
+  timer.unref();
+  try {
+    return await operation();
+  } finally {
+    clearInterval(timer);
+  }
+}
 async function saveImageItem(item, dir, base, apiKey) {
   if (item.b64_json) {
-    const filePath = join3(dir, `${base}.png`);
+    const ext = item.mime_type?.includes("jpeg") ? ".jpg" : item.mime_type?.includes("webp") ? ".webp" : ".png";
+    const filePath = join3(dir, `${base}${ext}`);
     await writeFile(filePath, Buffer.from(item.b64_json, "base64"));
     return filePath;
   }
@@ -864,21 +1132,88 @@ async function saveImageItem(item, dir, base, apiKey) {
   }
   throw new ApiError("bad_response", "\u56FE\u50CF\u7ED3\u679C\u65E2\u6CA1\u6709 url \u4E5F\u6CA1\u6709 b64_json");
 }
+function parseGenerationConfig(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error("not an object");
+    }
+    return parsed;
+  } catch {
+    throw new ApiError("invalid_request", "--config \u5FC5\u987B\u662F\u5408\u6CD5\u7684 generationConfig JSON \u5BF9\u8C61\u3002");
+  }
+}
+function parseJsonArray(raw, option) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) throw new Error("not an array");
+    return parsed;
+  } catch {
+    throw new ApiError("invalid_request", `--${option} must be a JSON array`);
+  }
+}
+function geminiImagePart(source) {
+  const dataUri = /^data:([^;,]+);base64,([a-z0-9+/=\r\n]+)$/i.exec(source.trim());
+  if (dataUri) {
+    const [, mimeType = "", data = ""] = dataUri;
+    return { inlineData: { mimeType, data: data.replace(/[\r\n]/g, "") } };
+  }
+  return { fileData: { fileUri: source } };
+}
+function extractGeminiImageItems(response) {
+  return (response.candidates ?? []).flatMap(
+    (candidate) => (candidate.content?.parts ?? []).flatMap(
+      (part) => part.inlineData?.data ? [{ b64_json: part.inlineData.data, mime_type: part.inlineData.mimeType }] : []
+    )
+  );
+}
 function registerGen(program) {
   const gen = program.command("gen").description("\u56FE\u50CF / \u89C6\u9891\u751F\u6210");
-  gen.command("image").description("\u751F\u6210\u56FE\u50CF\uFF08\u540C\u6B65\u8FD4\u56DE\uFF0C\u4EA7\u7269\u81EA\u52A8\u4E0B\u8F7D\u5230\u672C\u5730\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "\u56FE\u50CF\u6A21\u578B ID\uFF08focalapi models list \u67E5\u770B\uFF09").option("--size <size>", "\u5C3A\u5BF8\uFF0C\u5982 1024x1024").option("--n <count>", "\u5F20\u6570\uFF081\u2013128\uFF09", (v) => Number.parseInt(v, 10), 1).option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).action(async (promptParts, opts, cmd) => {
+  gen.command("image").description("\u751F\u6210\u56FE\u50CF\uFF08\u9ED8\u8BA4\u540C\u6B65\u8FD4\u56DE\u5E76\u4E0B\u8F7D\uFF1B--no-wait \u8FD4\u56DE\u53EF\u8F6E\u8BE2\u7684\u4EFB\u52A1 ID\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "\u56FE\u50CF\u6A21\u578B ID\uFF08focalapi models list \u67E5\u770B\uFF09").option("--size <size>", "\u5C3A\u5BF8\uFF0C\u5982 1024x1024").option("--quality <quality>", "\u56FE\u50CF\u8D28\u91CF\u6863\u4F4D\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09").option("--background <background>", "\u80CC\u666F\u6A21\u5F0F\uFF08\u4EC5 gpt-image-2 \u652F\u6301 auto/opaque\uFF09").option("--image <url...>", "\u53C2\u8003\u56FE\u6216\u7F16\u8F91\u56FE URL\uFF0C\u53EF\u591A\u4E2A").option("--mask <url>", "\u7F16\u8F91 mask URL\uFF08gpt-image-2 \u9700\u8981\u5355\u5F20\u53C2\u8003\u56FE\uFF09").option("--response-format <format>", "\u56FE\u50CF\u54CD\u5E94\u683C\u5F0F\uFF1Aurl \u6216 b64_json").option("--n <count>", "\u5F20\u6570\uFF081\u2013128\uFF09", (v) => Number.parseInt(v, 10), 1).option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u56FE\u50CF\u751F\u6210\u5B8C\u6210").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).action(async (promptParts, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
     const n = clampInt(opts.n, 1, MAX_IMAGE_N, "n");
+    validateImageGeneration(opts.model, {
+      n,
+      size: opts.size,
+      quality: opts.quality,
+      background: opts.background,
+      responseFormat: opts.responseFormat,
+      imageCount: opts.image?.length,
+      hasMask: Boolean(opts.mask)
+    });
+    if (opts.wait === false && opts.responseFormat === "b64_json") {
+      throw new ApiError("invalid_request", "--response-format b64_json cannot be used with --no-wait; use url");
+    }
     const body = { model: opts.model, prompt: promptParts.join(" "), n };
     if (opts.size) body.size = opts.size;
-    const res = await request({
+    if (opts.quality) body.quality = opts.quality;
+    if (opts.background) body.background = opts.background;
+    if (opts.image) body.image = opts.image;
+    if (opts.mask) body.mask = opts.mask;
+    if (opts.responseFormat) body.response_format = opts.responseFormat;
+    const res = await withProgress(opts.wait === false ? "\u6B63\u5728\u63D0\u4EA4\u56FE\u50CF\u4EFB\u52A1" : "\u6B63\u5728\u751F\u6210\u56FE\u50CF", () => request({
       baseUrl: auth.baseUrl,
       path: "/v1/images/generations",
       apiKey: auth.apiKey,
       body,
+      headers: opts.wait === false ? { Prefer: "respond-async" } : void 0,
       timeoutMs: 6e5
-    });
+    }));
+    if (opts.wait === false) {
+      const taskId = extractTaskId(res);
+      if (!taskId) {
+        throw new ApiError("bad_response", "\u5F02\u6B65\u56FE\u50CF\u4EFB\u52A1\u54CD\u5E94\u4E2D\u672A\u627E\u5230 task_id", { body: res });
+      }
+      if (g.json) {
+        printJson({ task_id: taskId, status: res.status ?? "queued", submitted: true });
+      } else {
+        process.stdout.write(taskId + "\n");
+        info(`\u4EFB\u52A1\u5DF2\u63D0\u4EA4\u3002\u67E5\u8BE2\uFF1Afocalapi task status ${taskId}`);
+      }
+      return;
+    }
     const items = res.data ?? [];
     if (items.length === 0) {
       throw new ApiError("bad_response", "\u56FE\u50CF\u751F\u6210\u54CD\u5E94\u4E3A\u7A7A", { body: res });
@@ -896,22 +1231,102 @@ function registerGen(program) {
       for (const f of files) info(`\u2713 ${f}`);
     }
   });
-  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u4EFB\u52A1\u5236\uFF1A\u9ED8\u8BA4\u8F6E\u8BE2\u81F3\u5B8C\u6210\u5E76\u4E0B\u8F7D\uFF1B--no-wait \u53EA\u53D6 task_id\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF08focalapi models list \u67E5\u770B\uFF09").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF081\u20133600\uFF09", (v) => Number.parseInt(v, 10)).option("--size <size>", "\u5206\u8FA8\u7387\uFF0C\u5982 1280x720").option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u5B8C\u6210").option("--poll-interval <ms>", "\u8F6E\u8BE2\u95F4\u9694\u6BEB\u79D2", (v) => Number.parseInt(v, 10), 5e3).option("--timeout <minutes>", "\u6700\u957F\u7B49\u5F85\u5206\u949F", (v) => Number.parseInt(v, 10), 30).option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).action(
+  gen.command("gemini-image").description("\u4F7F\u7528 Gemini \u539F\u751F generateContent \u63A5\u53E3\u751F\u6210\u56FE\u50CF").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "Gemini \u56FE\u50CF\u6A21\u578B ID\uFF1B\u5148\u7528 focalapi models get \u786E\u8BA4").option("--aspect-ratio <ratio>", "\u753B\u9762\u6BD4\u4F8B\uFF0C\u4F8B\u5982 1:1\u300116:9\u3001auto").option("--image-size <size>", "\u8F93\u51FA\u5C3A\u5BF8\uFF0C\u4F8B\u5982 1K\u30012K\u30014K").option("--config <json>", "\u9644\u52A0 Gemini generationConfig JSON\uFF1B\u547D\u4EE4\u56FA\u5B9A responseFormat.image \u548C\u5355\u5019\u9009").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--image <url...>", "Gemini reference image URL or data URI; repeatable").option("--system <text>", "Gemini systemInstruction text").option("--seed <n>", "Non-negative Gemini generation seed", (v) => Number.parseInt(v, 10)).option("--thinking-level <level>", "Nano Banana 2 Lite: MINIMAL or HIGH").option("--temperature <n>", "Nano Banana 2 Lite: 0 through 2", (v) => Number.parseFloat(v)).option("--top-p <n>", "Nano Banana 2 Lite: 0 through 1", (v) => Number.parseFloat(v)).action(async (promptParts, opts, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const auth = resolveAuth(g);
+    validateGeminiImageGeneration(opts.model, {
+      aspectRatio: opts.aspectRatio,
+      imageSize: opts.imageSize,
+      seed: opts.seed,
+      thinkingLevel: opts.thinkingLevel,
+      temperature: opts.temperature,
+      topP: opts.topP
+    });
+    const suppliedConfig = parseGenerationConfig(opts.config);
+    const suppliedResponseFormat = suppliedConfig.responseFormat;
+    const suppliedImageConfig = suppliedResponseFormat !== null && typeof suppliedResponseFormat === "object" && !Array.isArray(suppliedResponseFormat) ? suppliedResponseFormat.image : void 0;
+    const imageConfig = {
+      ...suppliedImageConfig !== null && typeof suppliedImageConfig === "object" && !Array.isArray(suppliedImageConfig) ? suppliedImageConfig : {},
+      ...opts.aspectRatio ? { aspectRatio: opts.aspectRatio } : {},
+      ...opts.imageSize ? { imageSize: opts.imageSize.toUpperCase() } : {}
+    };
+    const generationConfig = {
+      ...suppliedConfig,
+      candidateCount: 1,
+      responseFormat: { image: imageConfig },
+      ...opts.seed !== void 0 ? { seed: opts.seed } : {},
+      ...opts.thinkingLevel ? { thinkingConfig: { ...suppliedConfig.thinkingConfig ?? {}, thinkingLevel: opts.thinkingLevel.toUpperCase() } } : {},
+      ...opts.temperature !== void 0 ? { temperature: opts.temperature } : {},
+      ...opts.topP !== void 0 ? { topP: opts.topP } : {}
+    };
+    const res = await withProgress("\u6B63\u5728\u751F\u6210 Gemini \u56FE\u50CF", () => request({
+      baseUrl: auth.baseUrl,
+      path: `/v1beta/models/${encodeURIComponent(opts.model)}:generateContent`,
+      apiKey: auth.apiKey,
+      body: {
+        contents: [{ role: "user", parts: [{ text: promptParts.join(" ") }, ...(opts.image ?? []).map(geminiImagePart)] }],
+        ...opts.system ? { systemInstruction: { parts: [{ text: opts.system }] } } : {},
+        generationConfig
+      },
+      timeoutMs: 6e5
+    }));
+    const items = extractGeminiImageItems(res);
+    if (items.length === 0) {
+      throw new ApiError("bad_response", "Gemini \u56FE\u50CF\u54CD\u5E94\u4E2D\u672A\u627E\u5230 inlineData \u56FE\u50CF\u3002", { body: res });
+    }
+    const dir = resolve2(opts.out);
+    await mkdir2(dir, { recursive: true });
+    const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const files = [];
+    for (const [i, item] of items.entries()) {
+      files.push(await saveImageItem(item, dir, `gemini-image-${ts}-${i + 1}`, auth.apiKey));
+    }
+    if (g.json) {
+      printJson({ files, count: files.length });
+    } else {
+      for (const file of files) info(`\u2713 ${file}`);
+    }
+  });
+  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u4EFB\u52A1\u5236\uFF1A\u9ED8\u8BA4\u8F6E\u8BE2\u81F3\u5B8C\u6210\u5E76\u4E0B\u8F7D\uFF1B--no-wait \u53EA\u53D6 task_id\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF08focalapi models list \u67E5\u770B\uFF09").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF081\u20133600\uFF09", (v) => Number.parseInt(v, 10)).option("--size <size>", "\u5206\u8FA8\u7387\uFF0C\u5982 1280x720").option("--resolution <resolution>", "\u539F\u751F\u8F93\u51FA\u5206\u8FA8\u7387\uFF0C\u5982 480p\u3001720p\u30011080p\u30014k").option("--ratio <ratio>", "\u539F\u751F\u5BBD\u9AD8\u6BD4\uFF0C\u5982 16:9\u30019:16\u3001adaptive").option("--image <url...>", "\u56FE\u751F\u89C6\u9891\u7684\u6E90\u56FE\u50CF URL\uFF0C\u53EF\u591A\u4E2A").option("--generate-audio <boolean>", "\u662F\u5426\u751F\u6210\u97F3\u9891\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "generate-audio")).option("--watermark <boolean>", "\u662F\u5426\u6DFB\u52A0\u6C34\u5370\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "watermark")).option("--service-tier <tier>", "\u670D\u52A1\u5C42\u7EA7\uFF08Seedance 2.0 \u9ED8\u8BA4 default\uFF09").option("--priority <n>", "\u4EFB\u52A1\u4F18\u5148\u7EA7\uFF08\u4EC5 Seedance 2.0 \u6807\u51C6\u7248\uFF09", (v) => Number.parseInt(v, 10)).option("--callback-url <url>", "\u4EFB\u52A1\u5B8C\u6210\u56DE\u8C03 URL").option("--return-last-frame <boolean>", "\u662F\u5426\u8FD4\u56DE\u6700\u540E\u4E00\u5E27\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "return-last-frame")).option("--execution-expires-after <seconds>", "\u4EFB\u52A1\u8FC7\u671F\u79D2\u6570\uFF083600\u2013259200\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-identifier <identifier>", "Seedance \u5B89\u5168\u6807\u8BC6\u7B26\uFF081\u201364 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF09").option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u5B8C\u6210").option("--poll-interval <ms>", "\u8F6E\u8BE2\u95F4\u9694\u6BEB\u79D2", (v) => Number.parseInt(v, 10), 5e3).option("--timeout <minutes>", "\u6700\u957F\u7B49\u5F85\u5206\u949F", (v) => Number.parseInt(v, 10), 30).option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--content <json>", "Ark-compatible content JSON array; overrides prompt/image facade fields").action(
     async (promptParts, opts, cmd) => {
       const g = cmd.optsWithGlobals();
       const auth = resolveAuth(g);
       const body = { model: opts.model, prompt: promptParts.join(" ") };
+      const metadata = {};
       if (opts.seconds !== void 0) {
-        body.seconds = String(clampInt(opts.seconds, 1, MAX_TASK_DURATION_SECONDS, "seconds"));
+        const seconds = clampInt(opts.seconds, 1, MAX_TASK_DURATION_SECONDS, "seconds");
+        body.duration = seconds;
       }
       if (opts.size) body.size = opts.size;
-      const created = await request({
+      if (opts.image) body.images = opts.image;
+      if (opts.resolution) metadata.resolution = opts.resolution.toLowerCase();
+      if (opts.ratio) metadata.ratio = opts.ratio;
+      if (opts.generateAudio !== void 0) metadata.generate_audio = opts.generateAudio;
+      if (opts.watermark !== void 0) metadata.watermark = opts.watermark;
+      if (opts.serviceTier) metadata.service_tier = opts.serviceTier;
+      if (opts.priority !== void 0) metadata.priority = opts.priority;
+      if (opts.callbackUrl) metadata.callback_url = opts.callbackUrl;
+      if (opts.returnLastFrame !== void 0) metadata.return_last_frame = opts.returnLastFrame;
+      if (opts.executionExpiresAfter !== void 0) metadata.execution_expires_after = opts.executionExpiresAfter;
+      if (opts.safetyIdentifier) metadata.safety_identifier = opts.safetyIdentifier;
+      if (opts.content) metadata.content = parseJsonArray(opts.content, "content");
+      validateVideoGeneration(opts.model, {
+        seconds: opts.seconds,
+        resolution: opts.resolution,
+        ratio: opts.ratio,
+        serviceTier: opts.serviceTier,
+        priority: opts.priority,
+        executionExpiresAfter: opts.executionExpiresAfter,
+        safetyIdentifier: opts.safetyIdentifier
+      });
+      if (Object.keys(metadata).length > 0) body.metadata = metadata;
+      const created = await withProgress("\u6B63\u5728\u63D0\u4EA4\u89C6\u9891\u4EFB\u52A1", () => request({
         baseUrl: auth.baseUrl,
         path: "/v1/video/generations",
         apiKey: auth.apiKey,
         body,
         timeoutMs: 12e4
-      });
+      }));
       const taskId = extractTaskId(created);
       if (!taskId) {
         throw new ApiError("bad_response", "\u89C6\u9891\u4EFB\u52A1\u54CD\u5E94\u4E2D\u672A\u627E\u5230 task_id", { body: created });
@@ -980,63 +1395,6 @@ function registerTask(program) {
   });
 }
 
-// src/commands/search.ts
-import { readFileSync as readFileSync3 } from "fs";
-function extractResults(raw) {
-  if (!raw || typeof raw !== "object") return [];
-  const obj = raw;
-  const candidates = [obj.results, obj.data, obj.items, obj.output];
-  for (const c of candidates) {
-    if (!Array.isArray(c)) continue;
-    const out = [];
-    for (const item of c) {
-      if (!item || typeof item !== "object") continue;
-      const it = item;
-      const url = typeof it.url === "string" ? it.url : typeof it.link === "string" ? it.link : "";
-      const title = typeof it.title === "string" ? it.title : url;
-      const snippet = typeof it.snippet === "string" ? it.snippet : typeof it.content === "string" ? it.content.slice(0, 200) : void 0;
-      if (url || title) out.push({ title, url, ...snippet ? { snippet } : {} });
-    }
-    if (out.length > 0) return out;
-  }
-  return [];
-}
-function registerSearch(program) {
-  program.command("search").description("\u8054\u7F51\u641C\u7D22\uFF08/v1/alpha/search\uFF0Calpha \u7EA7\u63A5\u53E3\uFF09").argument("<query...>", "\u641C\u7D22\u5185\u5BB9").requiredOption("-m, --model <model>", "\u641C\u7D22\u6A21\u578B ID\uFF08focalapi models list --filter search \u67E5\u770B\uFF09").option("--raw <json|@file>", "\u5B8C\u6574\u81EA\u5B9A\u4E49\u8BF7\u6C42\u4F53\uFF08JSON \u5B57\u7B26\u4E32\u6216 @\u6587\u4EF6\uFF09\uFF0C\u4E0E query \u5408\u5E76").action(async (queryParts, opts, cmd) => {
-    const g = cmd.optsWithGlobals();
-    const auth = resolveAuth(g);
-    let body = { model: opts.model, query: queryParts.join(" ") };
-    if (opts.raw) {
-      const text = opts.raw.startsWith("@") ? readFileSync3(opts.raw.slice(1), "utf-8") : opts.raw;
-      try {
-        body = { ...JSON.parse(text), model: opts.model };
-      } catch {
-        throw new ApiError("invalid_request", "--raw \u4E0D\u662F\u5408\u6CD5 JSON");
-      }
-    }
-    const res = await request({
-      baseUrl: auth.baseUrl,
-      path: "/v1/alpha/search",
-      apiKey: auth.apiKey,
-      body,
-      timeoutMs: 12e4
-    });
-    if (g.json) {
-      printJson(res);
-      return;
-    }
-    const results = extractResults(res);
-    if (results.length === 0) {
-      printJson(res);
-      return;
-    }
-    printTable(
-      ["#", "\u6807\u9898", "\u94FE\u63A5"],
-      results.map((r, i) => [String(i + 1), r.title.slice(0, 60), r.url])
-    );
-  });
-}
-
 // src/commands/audio.ts
 import { writeFile as writeFile2 } from "fs/promises";
 import { resolve as resolve3 } from "path";
@@ -1087,77 +1445,15 @@ function registerAudio(program) {
   });
 }
 
-// src/commands/embed.ts
-function registerEmbed(program) {
-  program.command("embed").description("\u6587\u672C\u5411\u91CF\u5316\uFF08/v1/embeddings\uFF09").argument("[text...]", "\u6587\u672C\uFF1B\u7701\u7565\u4E14 stdin \u4E3A\u7BA1\u9053\u65F6\u4ECE stdin \u8BFB\u53D6").requiredOption("-m, --model <model>", "\u5411\u91CF\u6A21\u578B ID").option("--input <file>", "\u4ECE\u6587\u4EF6\u8BFB\u53D6\u6587\u672C\uFF08@ \u524D\u7F00\u53EF\u9009\uFF09").action(async (textParts, opts, cmd) => {
-    const g = cmd.optsWithGlobals();
-    const auth = resolveAuth(g);
-    let text = textParts.join(" ").trim();
-    if (opts.input) {
-      text = readInputFile(opts.input.replace(/^@/, "")).data.toString("utf-8");
-    } else if (!text && !process.stdin.isTTY) {
-      text = await readStdin();
-    }
-    if (!text) {
-      throw new ApiError("invalid_request", "\u7F3A\u5C11\u5F85\u5411\u91CF\u5316\u6587\u672C", {
-        hint: 'focalapi embed "\u6587\u672C" -m <model>\uFF0C\u6216 focalapi embed -m <model> --input @file.txt\u3002'
-      });
-    }
-    const res = await request({
-      baseUrl: auth.baseUrl,
-      path: "/v1/embeddings",
-      apiKey: auth.apiKey,
-      body: { model: opts.model, input: text },
-      timeoutMs: 12e4
-    });
-    if (g.json) {
-      printJson(res);
-    } else {
-      const vec = res.data?.[0]?.embedding ?? [];
-      info(`\u7EF4\u5EA6\uFF1A${vec.length}\uFF1Btokens\uFF1A${res.usage?.total_tokens ?? "-"}`);
-      info("\u5B8C\u6574\u5411\u91CF\u8BF7\u7528 --json \u8F93\u51FA\u3002");
-    }
-  });
-}
-
-// src/commands/rerank.ts
-import { readFileSync as readFileSync4 } from "fs";
-function registerRerank(program) {
-  program.command("rerank").description("\u6309\u67E5\u8BE2\u5BF9\u6587\u6863\u91CD\u6392\u5E8F\uFF08/v1/rerank\uFF09").requiredOption("-m, --model <model>", "rerank \u6A21\u578B ID").requiredOption("--query <text>", "\u67E5\u8BE2").requiredOption("--docs <json|@file>", "\u6587\u6863\u6570\u7EC4\uFF08JSON \u5B57\u7B26\u4E32\u6216 @file.json\uFF09").option("--top-n <n>", "\u53EA\u8FD4\u56DE\u524D N \u6761", (v) => Number.parseInt(v, 10)).action(async (opts, cmd) => {
-    const g = cmd.optsWithGlobals();
-    const auth = resolveAuth(g);
-    const text = opts.docs.startsWith("@") ? readFileSync4(opts.docs.slice(1), "utf-8") : opts.docs;
-    let documents;
-    try {
-      documents = JSON.parse(text);
-    } catch {
-      throw new ApiError("invalid_request", "--docs \u4E0D\u662F\u5408\u6CD5 JSON \u6570\u7EC4");
-    }
-    if (!Array.isArray(documents) || documents.length === 0) {
-      throw new ApiError("invalid_request", "--docs \u5FC5\u987B\u662F\u975E\u7A7A JSON \u6570\u7EC4");
-    }
-    const body = { model: opts.model, query: opts.query, documents };
-    if (opts.topN !== void 0) body.top_n = opts.topN;
-    const res = await request({
-      baseUrl: auth.baseUrl,
-      path: "/v1/rerank",
-      apiKey: auth.apiKey,
-      body,
-      timeoutMs: 12e4
-    });
-    if (g.json) {
-      printJson(res);
-      return;
-    }
-    const rows = (res.results ?? []).map((r) => {
-      const doc = typeof r.document === "string" ? r.document : r.document?.text ?? "";
-      return [String(r.index ?? "-"), String(r.relevance_score ?? "-"), doc.slice(0, 60)];
-    });
-    printTable(["\u539F\u6587\u6863\u5E8F\u53F7", "\u76F8\u5173\u5EA6", "\u6587\u6863\u9884\u89C8"], rows);
-  });
-}
-
 // src/commands/usage.ts
+function formatBillingUsage(billing) {
+  const value = billing.total_usage;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value.toLocaleString("zh-CN", { maximumFractionDigits: 4 });
+  }
+  if (typeof value === "string" && value.trim() !== "") return value;
+  return "-";
+}
 function defaultStartDate() {
   const now = /* @__PURE__ */ new Date();
   return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-01`;
@@ -1191,14 +1487,15 @@ function registerUsage(program) {
         ["\u5DF2\u7528", String(token.total_used)],
         ["\u5269\u4F59", token.unlimited_quota ? "\u65E0\u9650" : String(token.total_available)],
         ["\u8FC7\u671F\u65F6\u95F4", token.expires_at > 0 ? new Date(token.expires_at * 1e3).toLocaleString() : "\u6C38\u4E0D\u8FC7\u671F"],
-        [`\u5468\u671F\u7528\u91CF\uFF08${start} ~ ${end}\uFF09`, JSON.stringify(billing)]
+        [`\u5468\u671F\u7528\u91CF\uFF08${start} ~ ${end}\uFF09`, formatBillingUsage(billing)],
+        ["\u8D26\u5355\u5BF9\u8C61", typeof billing.object === "string" ? billing.object : "-"]
       ]
     );
   });
 }
 
 // src/commands/connect.ts
-import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync5, readdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, readdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir2, platform } from "os";
 import { dirname, join as join4 } from "path";
 import { fileURLToPath } from "url";
@@ -1290,7 +1587,7 @@ function readManifest(skillsDir) {
   const path = manifestPath(skillsDir);
   if (!existsSync2(path)) return void 0;
   try {
-    return JSON.parse(readFileSync5(path, "utf-8"));
+    return JSON.parse(readFileSync3(path, "utf-8"));
   } catch {
     return void 0;
   }
@@ -1513,16 +1810,13 @@ function registerRequest(program) {
 // src/cli.ts
 function buildProgram() {
   const program = new Command();
-  program.name("focalapi").description("\u8FDE\u63A5 focalapi \u4E0E AI Agent \u7684\u547D\u4EE4\u884C\u5DE5\u5177\uFF1A\u5BF9\u8BDD\u3001\u56FE\u50CF\u3001\u89C6\u9891\u3001\u641C\u7D22\u3001\u97F3\u9891\u3001\u7528\u91CF\uFF0C\u4E00\u6761\u547D\u4EE4\u76F4\u8FBE").version(VERSION, "-v, --version", "\u663E\u793A\u7248\u672C\u53F7").option("--json", "\u4EE5 JSON \u8F93\u51FA\uFF08\u9762\u5411 Agent \u4E0E\u811A\u672C\uFF0Cstdout \u7EAF\u51C0\uFF09").option("--base-url <url>", "\u8986\u76D6 API \u5730\u5740\uFF08\u9ED8\u8BA4 https://api.focalapi.com\uFF0C\u53EF\u7528 FOCALAPI_BASE_URL\uFF09").option("--key <key>", "\u8986\u76D6 API Key\uFF08\u53EF\u7528 FOCALAPI_API_KEY\uFF09").option("--profile <name>", "\u4F7F\u7528\u6307\u5B9A\u914D\u7F6E\u6863\u6848");
+  program.name("focalapi").description("\u9762\u5411\u521B\u4F5C\u5DE5\u4F5C\u6D41\u7684 focalapi CLI\uFF1A\u56FE\u50CF\u3001\u89C6\u9891\u3001\u97F3\u9891\u4E0E DeepSeek \u5907\u7528\u6587\u672C\u80FD\u529B\uFF0C\u4E00\u6761\u547D\u4EE4\u76F4\u8FBE").version(VERSION, "-v, --version", "\u663E\u793A\u7248\u672C\u53F7").option("--json", "\u4EE5 JSON \u8F93\u51FA\uFF08\u9762\u5411 Agent \u4E0E\u811A\u672C\uFF0Cstdout \u7EAF\u51C0\uFF09").option("--base-url <url>", "\u8986\u76D6 API \u5730\u5740\uFF08\u9ED8\u8BA4 https://api.focalapi.com\uFF0C\u53EF\u7528 FOCALAPI_BASE_URL\uFF09").option("--key <key>", "\u8986\u76D6 API Key\uFF08\u53EF\u7528 FOCALAPI_API_KEY\uFF09").option("--profile <name>", "\u4F7F\u7528\u6307\u5B9A\u914D\u7F6E\u6863\u6848");
   registerAuth(program);
   registerModels(program);
   registerChat(program);
   registerGen(program);
   registerTask(program);
-  registerSearch(program);
   registerAudio(program);
-  registerEmbed(program);
-  registerRerank(program);
   registerUsage(program);
   registerDoctor(program);
   registerConnect(program);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "focalapi-cli",
-  "version": "0.1.0",
-  "description": "连接 focalapi 与 AI Agent 的命令行工具——让 Agent 直接调用 focalapi 的对话、图像、视频、搜索、音频等模型能力",
+  "version": "0.1.1",
+  "description": "连接 focalapi 创作模型与 AI Agent 的命令行工具——图像、视频、音频与 DeepSeek 备用文本能力",
   "type": "module",
   "bin": {
     "focalapi": "dist/cli.js"

package/skills/focalapi/SKILL.md

@@ -1,43 +1,43 @@
 ---
 name: focalapi
-description: focalapi 能力总入口。Use when 用户要求使用 focalapi / focalapi-cli，或需要调用 focalapi 的对话、图像、视频、搜索、音频、向量、重排、用量等任意模型能力。先读本技能确定该用哪个子技能/命令。
+description: focalapi 创作能力总入口。Use when 用户需要生成或处理图像、视频、音频、3D 或其他视觉创作内容；DeepSeek 仅用于提示词、分镜和轻量文本辅助。先读本技能选择对应的子技能或命令。
 ---
 
-# focalapi 能力总览
+# focalapi 创作能力总览
 
-focalapi 是统一的 AI 模型 API 网关（OpenAI 兼容），`focalapi` CLI 让 Agent 一条命令调用全部能力。
+focalapi 是面向创作工作流的模型中转服务。`focalapi` CLI 让 Agent 用命令完成图像、视频、音频与其他视觉创作任务；通用文本只将 DeepSeek 作为备用能力。
 
 ## 前置检查
 
 ```bash
-focalapi --version          # 确认 CLI 已安装
-focalapi auth status        # 确认 Key 有效、看额度
-focalapi doctor             # 全链路自检（用免费演练模型，不花额度）
+focalapi --version
+focalapi auth status
+focalapi models list --json
+# 选定创作模型后，读取支持参数、端点与默认值
+focalapi models get <模型ID> --json
 ```
 
-任何命令失败，先跑 `focalapi doctor` 按提示修复（Key 缺失 → `focalapi auth login --key <sk-...>`）。
+模型、参数、并发和价格始终以 `focalapi models list --json` 与控制台模型广场的实际结果为准。命令失败时，先执行 `focalapi doctor` 排查 Key、网络与额度。
 
 ## 能力 → 命令速查
 
 | 需求 | 命令 | 子技能 |
 |---|---|---|
-| 对话/总结/翻译/看图 | `focalapi chat` | focalapi-chat |
-| 生成图片 | `focalapi gen image` | focalapi-gen |
+| 生成或编辑图像 | `focalapi gen image`（可 `--no-wait` 提交持久任务） | focalapi-gen |
+| 生成 Gemini 原生图像 | `focalapi gen gemini-image` | focalapi-gen |
 | 生成视频 | `focalapi gen video`（任务制，可 `--no-wait`） | focalapi-gen |
-| 联网搜索 | `focalapi search` | focalapi-search |
+| 查询任务或下载视频产物 | `focalapi task status` / `focalapi task download` | focalapi-gen |
 | 语音转文字 | `focalapi audio transcribe` | focalapi-chat |
 | 文字转语音 | `focalapi audio speech` | focalapi-chat |
-| 文本向量化 | `focalapi embed` | focalapi-chat |
-| 文档重排序 | `focalapi rerank` | focalapi-chat |
-| 额度/用量 | `focalapi usage` / `focalapi auth status` | focalapi-usage |
-| 诊断排障 | `focalapi doctor` | focalapi-usage |
-| 读取未封装端点 | `focalapi request get /v1/... --json` | focalapi |
-
-## Agent 使用约定
-
-1. **机器可读输出**：所有命令加 `--json`，stdout 是纯净 JSON，可直接 `jq` 解析。
-2. **模型选择**：先 `focalapi models list --json` 拿当前 Key 可用模型，不要猜模型名。
-3. **演练模型**：`focal-rehearsal-chat` 免费，适合做链路验证和演示。
-4. **产物路径**：生成类命令默认写入 `./focalapi-out/`，把绝对路径告诉用户。
-5. **非交互**：本 CLI 在非 TTY 环境全自动（无提示无动画），认证用环境变量 `FOCALAPI_API_KEY` 或已保存的配置。
-6. **原始请求**：优先用语义化命令；只有读取尚未封装的端点时才用 `request get` / `request head`。它只允许站内路径和 GET/HEAD，绝不用于写入操作。
+| 提示词、分镜或脚本辅助 | `focalapi chat -m <DeepSeek 模型>` | focalapi-chat |
+| 额度与诊断 | `focalapi usage` / `focalapi doctor` | focalapi-usage |
+| 查询可用模型 | `focalapi models list --json` | focalapi |
+
+## 使用约定
+
+1. **创作优先**：图像、视频、音频和视觉模型是默认选择。3D 或其他视觉模型是否可用，以模型列表为准。
+2. **文本边界**：仅在提示词、分镜、旁白草稿或轻量文本任务中使用 DeepSeek；不要假设其他文本、编码或聊天模型可用。
+3. **机器可读输出**：命令加 `--json` 时，stdout 只输出 JSON。
+4. **先查模型再调用**：不能猜测模型 ID；先运行 `focalapi models list --json`，选定模型后运行 `focalapi models get <模型ID> --json`，以 `supported_endpoint_types` 和 `supported_params` 为准。
+5. **产物路径**：生成类命令默认写入 `./focalapi-out/`，完成后向用户报告绝对路径。
+6. **原始只读请求**：优先使用语义化命令；只有读取尚未封装的端点时才使用 `request get` / `request head`。

package/skills/focalapi-chat/SKILL.md

@@ -1,51 +1,29 @@
 ---
 name: focalapi-chat
-description: 用 focalapi 做对话、多模态理解（看图）、embedding 与 rerank。Use when 需要文本生成/总结/翻译/问答、理解图片内容、文本向量化或文档重排序。
+description: 用 DeepSeek 作为创作流程的文本备用能力，并通过 focalapi 处理音频转写和语音合成。Use when 用户需要提示词、分镜、脚本草稿、看图辅助、音频转写或文字转语音。
 ---
 
-# focalapi 对话与理解
+# focalapi 文本辅助与音频
 
-## 对话
+## DeepSeek 文本辅助
 
-```bash
-# 基础（模型名先从 focalapi models list 获取；演练用免费 focal-rehearsal-chat）
-focalapi chat "用一句话总结 RAG" -m <model>
-
-# 管道输入（处理长文本/文件内容）
-cat report.md | focalapi chat -m <model> --system "你是严谨的技术编辑"
-
-# 看图（多模态）
-focalapi chat "描述这张图的 UI 布局" -m <多模态模型> --input @screenshot.png
-
-# 机器可读输出（Agent 串联）
-focalapi chat "提取关键日期" -m <model> --json
-```
-
-- `--stream` / `--no-stream` 控制流式（TTY 默认流式，`--json` 默认非流式）。
-- `--input` 支持多张图片；txt/md/json 文件会作为文本拼入。
-- 默认模型可用 `FOCALAPI_MODEL` 环境变量固定。
-
-## 向量化
+DeepSeek 是 focalapi 唯一对外展示的通用文本备用能力。先查询可用模型，再用于提示词、分镜、旁白与轻量脚本任务：
 
 ```bash
-focalapi embed "待编码文本" -m <embedding模型> --json
-focalapi embed -m <model> --input @doc.txt --json
+focalapi models list --json
+focalapi chat "把这个产品简介写成 6 镜头分镜" -m <DeepSeek模型>
 ```
 
-## 重排序
-
-```bash
-focalapi rerank -m <rerank模型> --query "用户问题" --docs @docs.json --json
-# docs.json 是字符串数组
-```
+- 不要猜测模型 ID，也不要假设其他文本或编码模型可用。
+- 需要结构化输出时使用 `--json`；长结果可加 `--stream`。
+- `--input @image.png` 可把图片作为辅助输入；图像生成请改用 `focalapi gen image`。
 
 ## 音频
 
 ```bash
-focalapi audio transcribe meeting.mp3 -m <转写模型>          # 语音→文字
-focalapi audio speech "大家好" -m <TTS模型> --voice alloy -o out.mp3
+focalapi audio transcribe interview.mp3 -m <转写模型>
+focalapi audio speech "这里是一段旁白" -m <语音模型> -o narration.mp3
 ```
 
-## 排错
-
-失败先 `focalapi doctor`；报 model_not_found 时 `focalapi models list --filter <关键字>` 确认模型名。
+- 音频模型、可用音色和格式以 `focalapi models list --json` 为准。
+- 批量任务前先用短样本确认质量和单价。

package/skills/focalapi-gen/SKILL.md

@@ -7,9 +7,29 @@ description: 用 focalapi 生成图片和视频（产物自动下载到本地）
 
 ## 图片（同步）
 
+调用创作模型前，先读取它的机器可读契约；不要猜测尺寸、时长或原生端点：
+
+```bash
+focalapi models get <模型ID> --json
+```
+
+响应中的 `supported_endpoint_types` 指明应使用的 API 协议，`supported_params` 列出参数、默认值、枚举和边界。CLI 会提前拒绝已知无效参数；应修正参数，不要将同一参数重试给上游。
+
 ```bash
 focalapi gen image "未来城市夜景海报，赛博朋克风" -m <图像模型> --size 1024x1024 -o ./out
 # 多张：--n 4（上限 128）
+# 参考图/编辑：image 可重复给 URL；response-format 只接受 url 或 b64_json
+focalapi gen image "将背景改为雨夜" -m gpt-image-2 --image https://example.com/source.png \
+  --mask https://example.com/mask.png --response-format b64_json -o ./out
+# 长任务编排：--no-wait 要求服务端持久化任务，返回 task_id；图像结果从 task status 的 raw.data 读取 URL
+focalapi gen image "未来城市夜景海报，赛博朋克风" -m gpt-image-2 --size 1024x1024 --no-wait --json
+focalapi task status <task_id> --json
+
+# Gemini 图像模型必须走原生 Gemini generateContent 端点，不能使用 gen image
+focalapi gen gemini-image "未来城市夜景海报，赛博朋克风" -m gemini-3.1-flash-image-preview \
+  --aspect-ratio 16:9 --image-size 2K -o ./out
+# Gemini named flags cover --image, --system, --seed, --thinking-level, --temperature, and --top-p.
+# For another documented generationConfig field, use --config; the command keeps responseFormat.image and candidateCount=1 authoritative.
 ```
 
 产物保存到 `-o` 目录（默认 `./focalapi-out/`），stdout/stderr 会打印绝对路径，把路径直接交给用户或后续步骤。
@@ -20,6 +40,20 @@ focalapi gen image "未来城市夜景海报，赛博朋克风" -m <图像模型
 # 方式一：前台等待完成并自动下载（默认）
 focalapi gen video "海浪拍打礁石，电影感" -m <视频模型> --seconds 5 -o ./out
 
+# Seedance 2.0：使用模型原生参数。Fast/Mini 只支持 480p 和 720p；所有 Seedance 2.0 时长为 4–15 秒。
+focalapi gen video "海浪拍打礁石，电影感" -m doubao-seedance-2-0-260128 \
+  --seconds 5 --resolution 720p --ratio 16:9 --generate-audio true --no-wait --json
+
+# 图生视频与 Seedance 的任务控制参数会映射到请求 metadata；布尔参数必须显式为 true 或 false
+focalapi gen video "让海浪缓慢推进" -m doubao-seedance-2-0-260128 \
+  --image https://example.com/frame.png --generate-audio false --watermark true \
+  --return-last-frame true --callback-url https://example.com/callback \
+  --execution-expires-after 7200 --safety-identifier customer-42 --priority 4 --no-wait --json
+
+# Ark-compatible metadata.content keeps native text/image_url/video_url/audio_url items and roles unchanged:
+focalapi gen video "ignored when content is supplied" -m doubao-seedance-2-0-260128 \
+  --content '[{"type":"text","text":"A cinematic ocean wave."}]' --no-wait --json
+
 # 方式二：异步——Agent 做长任务编排时推荐
 focalapi gen video "..." -m <视频模型> --no-wait --json     # 立即拿 task_id
 focalapi task status <task_id> --json                      # 轮询状态
@@ -33,6 +67,8 @@ focalapi task download <task_id> -o ./out                  # 完成后取 mp4
 ## JSON 输出约定（供 Agent 解析）
 
 - `gen image --json` → `{"files": ["..."], "count": N}`
+- `gen image --no-wait --json` → `{"task_id": "...", "status": "queued", "submitted": true}`
+- `gen gemini-image --json` → `{"files": ["..."], "count": N}`
 - `gen video --no-wait --json` → `{"task_id": "...", "submitted": true}`
 - `gen video --json`（等待模式）→ `{"task_id": "...", "status": "success", "file": "..."}`
 - `task status --json` → `{"task_id","status":"pending|running|success|failed|unknown","progress","raw"}`

package/skills/focalapi-search/SKILL.md

@@ -1,31 +0,0 @@
----
-name: focalapi-search
-description: 用 focalapi 联网搜索。Use when 需要实时信息、新闻、资料检索、事实核查，或用户明确要求"搜一下/查一下"。
----
-
-# focalapi 联网搜索
-
-```bash
-focalapi search "过去7天 AI 行业重要新闻" -m <搜索模型> --json
-```
-
-- 端点为 `/v1/alpha/search`（alpha 级，响应结构由上游定义）；`--json` 原样透传，pretty 模式尽力解析为结果表格。
-- 搜索模型名先确认：`focalapi models list --filter search`。
-
-## 自定义请求体（逃生门）
-
-上游格式变更或需要高级参数时，用 `--raw` 直接控制请求体：
-
-```bash
-focalapi search "查询" -m <model> --raw '{"query":"...","search_depth":"advanced"}' --json
-focalapi search x -m <model> --raw @body.json
-```
-
-## 典型编排
-
-搜索 → 把 `--json` 结果交给 `focalapi chat` 做摘要/分析：
-
-```bash
-focalapi search "主题" -m <搜索模型> --json > results.json
-cat results.json | focalapi chat -m <对话模型> --system "把输入的搜索结果整理成 5 条要点"
-```