focalapi-cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 - 2026-08-18
+
+- Added `task cancel` for queued tasks through `DELETE /v1/video/generations/{task_id}`, including the 409 `task_already_running` / `task_already_finished` and 502 `task_cancel_failed` contract with actionable hints.
+- Added `gen video --first-frame <url>` for image-to-video and made `--image` the reference-media channel; Grok 1.5 reference-to-video is capped at 720p and 7 images locally, the legacy Grok video model rejects references outright, and the two flags are mutually exclusive.
+- Accepted the new Seedance 2.5 1080p tier and wired per-model reference-image caps (Seedance, Omni, Kling, Vidu, LTX, FLUX).
+- Aligned Gemini image validation: `gemini-2.5-flash-image` accepts at most 1 `inlineData` reference, `gemini-3.1-flash-image` gains the 15-value ratio surface and `thinkingLevel`/`temperature`/`topP`, and seeds are capped at `Number.MAX_SAFE_INTEGER`.
+- Corrected `seedream-4-0-250828` default size to `2k`, lowered the Vidu seed ceiling to 2147483647, and capped FLUX 3 `safety_tolerance` at 2 whenever images are attached.
+- Normalized task statuses `cancelled`, `expired`, and the `queued_*` family, with refund-aware messaging for expired tasks.
+- Mapped the platform's 503 `capacity_exhausted` signal to a stable retryable error code with a retry hint instead of a generic server error.
+- Refreshed the bundled Agent Skills and README with the cancel workflow, capacity retry guidance, and the Grok video mode contract.
+
 ## 0.2.2 - 2026-08-14
 
 - Removed the retired Veo 3.1 preview models from automatic video selection and local validation.

package/README.md

@@ -50,6 +50,9 @@ focalapi gen video "Ocean waves hitting rocks, cinematic" --no-wait -o ./out --j
 # Continue from next_command in the generation response without resubmitting the task.
 focalapi task status <task-id> --json
 focalapi task download <task-id> -o ./out --json
+
+# Stop a task that is still queued; cancelled tasks are refunded automatically.
+focalapi task cancel <task-id> --json
 ```
 
 When the user specifies a model, read its authoritative contract first:
@@ -68,7 +71,7 @@ focalapi models resolve video --json
 
 `resolve` returns the exact `model.id`, verified `endpoint_type`, complete `supported_params`, candidate models, and a `next_command`. When a list summary and detailed contract disagree, the detailed contract is authoritative.
 
-The maintained creative defaults are aligned with the current catalog: Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images; Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, FLUX 3, and MiniMax H3 for video. Availability still depends on the current key, so runtime model details always take precedence over this overview.
+The maintained creative defaults are aligned with the current catalog: Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images; Seedance 2.5 (480p/720p/1080p), Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, and FLUX 3 for video. Availability still depends on the current key, so runtime model details always take precedence over this overview.
 
 ## Agent integration
 
@@ -112,7 +115,7 @@ The fully validated automatic generation paths currently cover images and video,
 | Generate images with automatic or explicit model selection | `focalapi gen image` |
 | Generate video with automatic or explicit model selection | `focalapi gen video` |
 | Resolve models and inspect live contracts | `focalapi models resolve/get/search/list` |
-| Check and download asynchronous tasks | `focalapi task status/download` |
+| Check, cancel (queued), and download asynchronous tasks | `focalapi task status/cancel/download` |
 | Sign in and inspect key status | `focalapi auth login/status/logout` |
 | Inspect quota, usage, and diagnostics | `focalapi usage`, `focalapi doctor` |
 | Connect Agent Skills | `focalapi connect` |

package/dist/cli.js

@@ -37,6 +37,20 @@ var ApiError = class extends Error {
     };
   }
 };
+var ERROR_HINTS = {
+  missing_api_key: "\u672A\u914D\u7F6E API Key\u3002\u8FD0\u884C focalapi auth login --key <sk-...>\uFF0C\u6216\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF FOCALAPI_API_KEY\u3002",
+  invalid_api_key: "API Key \u65E0\u6548\u3001\u5DF2\u8FC7\u671F\u6216\u88AB\u5220\u9664\u3002\u524D\u5F80 https://focalapi.com/console/token \u68C0\u67E5\u6216\u65B0\u5EFA Key\uFF0C\u7136\u540E\u91CD\u65B0 focalapi auth login\u3002",
+  insufficient_quota: "\u8D26\u6237\u989D\u5EA6\u4E0D\u8DB3\u3002\u524D\u5F80 https://focalapi.com/console/topup \u5145\u503C\uFF1B\u53EF\u8FD0\u884C focalapi usage \u67E5\u770B\u5F53\u524D\u989D\u5EA6\u3002",
+  rate_limited: "\u8BF7\u6C42\u89E6\u53D1\u9650\u6D41\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
+  capacity_exhausted: "\u5E73\u53F0\u521B\u4F5C\u5BB9\u91CF\u5DF2\u6EE1\uFF08\u6392\u961F\u51C6\u5165\u8FBE\u5230\u4E0A\u9650\uFF0CHTTP 503\uFF09\u3002\u670D\u52A1\u7AEF\u5EFA\u8BAE\u7EA6 10 \u79D2\u540E\u91CD\u8BD5\uFF1A\u76F4\u63A5\u91CD\u8DD1\u540C\u4E00\u6761\u547D\u4EE4\u5373\u53EF\uFF0C\u65E0\u9700\u4FEE\u6539\u53C2\u6570\u6216\u66F4\u6362\u6A21\u578B\u3002",
+  model_not_found: "\u6A21\u578B\u4E0D\u5B58\u5728\u6216\u672A\u5BF9\u4F60\u7684 Key \u5F00\u653E\u3002\u8FD0\u884C focalapi models list \u67E5\u770B\u53EF\u7528\u6A21\u578B\u3002",
+  network_error: "\u65E0\u6CD5\u8FDE\u63A5 focalapi \u670D\u52A1\u3002\u68C0\u67E5\u7F51\u7EDC\u4EE3\u7406\u4E0E FOCALAPI_BASE_URL \u914D\u7F6E\uFF1B\u53EF\u8FD0\u884C focalapi doctor \u505A\u94FE\u8DEF\u8BCA\u65AD\u3002",
+  timeout: "\u8BF7\u6C42\u8D85\u65F6\u3002\u7A0D\u540E\u91CD\u8BD5\uFF0C\u6216\u8FD0\u884C focalapi doctor \u68C0\u67E5\u94FE\u8DEF\u8D28\u91CF\u3002",
+  server_error: "focalapi \u670D\u52A1\u7AEF\u9519\u8BEF\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002\u82E5\u6301\u7EED\u51FA\u73B0\uFF0C\u8BF7\u643A\u5E26\u9519\u8BEF\u4FE1\u606F\u53CD\u9988\u7ED9\u670D\u52A1\u65B9\u3002",
+  invalid_request: "\u8BF7\u6C42\u53C2\u6570\u6709\u8BEF\uFF0C\u8BF7\u68C0\u67E5\u547D\u4EE4\u53C2\u6570\u3002",
+  authentication_failed: "\u9274\u6743\u5931\u8D25\u3002\u5148\u8FD0\u884C focalapi auth status \u9A8C\u8BC1\u672C\u7AD9 Key\uFF1B\u82E5\u672C\u7AD9 Key \u6709\u6548\uFF0C\u5219\u8BF7\u5C06\u8BF7\u6C42 ID \u63D0\u4F9B\u7ED9\u670D\u52A1\u65B9\u6392\u67E5\u6E20\u9053\u6743\u9650\u3002",
+  upstream_auth_failed: "\u4E0A\u6E38\u6E20\u9053\u9274\u6743\u5931\u8D25\uFF0C\u5E76\u4E0D\u8868\u793A\u4F60\u7684 FocalAPI Key \u65E0\u6548\u3002\u5148\u8FD0\u884C focalapi auth status\uFF1B\u82E5\u901A\u8FC7\uFF0C\u8BF7\u5C06\u8BF7\u6C42 ID \u63D0\u4F9B\u7ED9\u670D\u52A1\u65B9\u6392\u67E5\u6E20\u9053\u914D\u7F6E\u3002"
+};
 function refineErrorCode(status, message, opts) {
   const m = message.toLowerCase();
   if (m.includes("quota") || m.includes("\u989D\u5EA6") || m.includes("insufficient")) {
@@ -104,8 +118,15 @@ function printJson(data) {
 function info(message) {
   process.stderr.write(message + "\n");
 }
-function printError(err, opts) {
-  if (err instanceof ApiError) {
+function printError(errInput, opts) {
+  if (errInput instanceof ApiError) {
+    const err = !errInput.hint && ERROR_HINTS[errInput.code] ? new ApiError(errInput.code, errInput.message, {
+      status: errInput.status,
+      hint: ERROR_HINTS[errInput.code],
+      body: errInput.body,
+      upstreamCode: errInput.upstreamCode,
+      requestId: errInput.requestId
+    }) : errInput;
     if (opts?.json) {
       printJson(err.toJSON());
     } else {
@@ -127,7 +148,7 @@ function printError(err, opts) {
     }
     return;
   }
-  const message = err instanceof Error ? err.message : String(err);
+  const message = errInput instanceof Error ? errInput.message : String(errInput);
   if (opts?.json) {
     printJson({ error: { code: "internal_error", message } });
   } else {
@@ -155,7 +176,7 @@ function displayWidth(s) {
 }
 
 // src/lib/version.ts
-var VERSION = true ? "0.2.2" : "0.0.0-dev";
+var VERSION = true ? "0.3.0" : "0.0.0-dev";
 
 // src/commands/auth.ts
 import { createInterface } from "readline/promises";
@@ -319,7 +340,10 @@ async function rawRequest(opts) {
   if (!res.ok) {
     const text = await res.text().catch(() => "");
     const { message, body, upstreamCode } = extractErrorMessage(text);
-    const code = refineErrorCode(res.status, message, { authFailureIsInvalidApiKey: opts.authFailureIsInvalidApiKey });
+    let code = refineErrorCode(res.status, message, { authFailureIsInvalidApiKey: opts.authFailureIsInvalidApiKey });
+    if (upstreamCode === "capacity_exhausted" || res.status === 503 && /capacity/i.test(message)) {
+      code = "capacity_exhausted";
+    }
     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 });
   }
@@ -485,7 +509,6 @@ var RECOMMENDED_MODELS = {
     "grok-imagine-video-1.5",
     "ltx-2-5-fast",
     "flux-3",
-    "MiniMax-H3",
     "dreamina-seedance-2-0-260128"
   ]
 };
@@ -895,6 +918,7 @@ import { pipeline as pipeline2 } from "stream/promises";
 import { Readable as Readable2 } from "stream";
 
 // src/lib/model-capabilities.ts
+var GEMINI_IMAGE_MAX_SEED = 9007199254740991;
 var SEEDREAM_OUTPUT_FORMATS = ["png", "jpeg"];
 var SEEDREAM_OPTIMIZE_PROMPT_MODES = ["auto", "enabled", "disabled"];
 var GROK_IMAGE_ASPECT_RATIOS = [
@@ -946,7 +970,7 @@ var IMAGE_CONSTRAINTS = {
     backgrounds: ["auto", "opaque"]
   },
   "seedream-4-0-250828": {
-    defaultSize: "1k",
+    defaultSize: "2k",
     sizeTiers: ["1k", "2k", "4k"],
     maxN: 10,
     maxReferenceImages: 10,
@@ -1087,7 +1111,6 @@ var SEEDANCE_RATIOS = ["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"];
 var GROK_VIDEO_ASPECT_RATIOS = ["auto", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16"];
 var KLING_VIDEO_ASPECT_RATIOS = ["16:9", "9:16", "1:1"];
 var VIDU_VIDEO_ASPECT_RATIOS = ["16:9", "9:16", "3:4", "4:3", "1:1"];
-var MINIMAX_VIDEO_RATIOS = ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive"];
 var FLUX_VIDEO_RATIOS = ["auto", "21:9", "2:1", "16:9", "4:3", "1:1", "3:4", "9:16"];
 var VIDEO_CONSTRAINTS = {
   "dreamina-seedance-2-0-260128": {
@@ -1095,55 +1118,65 @@ var VIDEO_CONSTRAINTS = {
     ratios: SEEDANCE_RATIOS,
     minSeconds: 4,
     maxSeconds: 15,
-    supportsPriority: true
+    maxReferenceImages: 9
   },
   "dreamina-seedance-2-0-fast-260128": {
     resolutions: ["480p", "720p"],
     ratios: SEEDANCE_RATIOS,
     minSeconds: 4,
     maxSeconds: 15,
-    supportsPriority: true
+    maxReferenceImages: 9
   },
-  "dreamina-seedance-2-0-mini-260615": {
+  "seed-2-0-mini-260428": {
     resolutions: ["480p", "720p"],
     ratios: SEEDANCE_RATIOS,
     minSeconds: 4,
     maxSeconds: 15,
-    supportsPriority: true
+    maxReferenceImages: 9
   },
   "dreamina-seedance-2-5-260628": {
-    resolutions: ["480p", "720p"],
+    resolutions: ["480p", "720p", "1080p"],
     ratios: SEEDANCE_RATIOS,
     minSeconds: 4,
-    maxSeconds: 30
+    maxSeconds: 30,
+    maxReferenceImages: 30
   },
   "gemini-omni-flash-preview": {
     resolutions: [],
     ratios: ["16:9", "9:16"],
     minSeconds: 3,
-    maxSeconds: 10
+    maxSeconds: 10,
+    maxReferenceImages: 14,
+    supportsGenerateAudio: false
   },
   "grok-imagine-video": {
-    resolutions: ["480p", "720p", "1080p"],
+    resolutions: ["480p", "720p"],
     aspectRatios: GROK_VIDEO_ASPECT_RATIOS,
     minSeconds: 1,
     maxSeconds: 15,
-    supportsSeed: true,
-    maxSeed: 2147483647
+    disallowReferences: true,
+    maxFirstFrameImages: 1,
+    supportsGenerateAudio: false,
+    supportsWatermark: false
   },
   "grok-imagine-video-1.5": {
     resolutions: ["480p", "720p", "1080p"],
     aspectRatios: GROK_VIDEO_ASPECT_RATIOS,
     minSeconds: 1,
     maxSeconds: 15,
-    supportsSeed: true,
-    maxSeed: 2147483647
+    maxReferenceImages: 7,
+    referenceResolutions: ["480p", "720p"],
+    maxFirstFrameImages: 1,
+    supportsGenerateAudio: false,
+    supportsWatermark: false
   },
   "kling-3.0": {
     resolutions: ["720p", "1080p", "4k"],
     aspectRatios: KLING_VIDEO_ASPECT_RATIOS,
     minSeconds: 3,
-    maxSeconds: 15
+    maxSeconds: 15,
+    maxReferenceImages: 2,
+    supportsGenerateAudio: true
   },
   "viduq3-pro": {
     resolutions: ["720p", "1080p"],
@@ -1151,7 +1184,8 @@ var VIDEO_CONSTRAINTS = {
     minSeconds: 1,
     maxSeconds: 16,
     supportsSeed: true,
-    maxSeed: 2147483647
+    maxSeed: 2147483647,
+    maxReferenceImages: 2
   },
   "viduq3-turbo": {
     resolutions: ["720p", "1080p"],
@@ -1159,49 +1193,67 @@ var VIDEO_CONSTRAINTS = {
     minSeconds: 1,
     maxSeconds: 16,
     supportsSeed: true,
-    maxSeed: 2147483647
-  },
-  "MiniMax-H3": {
-    resolutions: ["768p", "2k"],
-    ratios: MINIMAX_VIDEO_RATIOS,
-    minSeconds: 5,
-    maxSeconds: 15
+    maxSeed: 2147483647,
+    maxReferenceImages: 2
   },
   "ltx-2-5-fast": {
     resolutions: ["1280x720", "720x1280", "1920x1080", "1080x1920", "2560x1440", "1440x2560", "3840x2160", "2160x3840"],
-    minSeconds: 2,
+    minSeconds: 6,
     maxSeconds: 20,
-    allowedSeconds: [2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 18, 20],
-    supportsSeed: true,
-    maxSeed: 4294967295,
-    allowedFps: [24, 25, 48, 50]
+    allowedSeconds: [6, 8, 10, 12, 14, 16, 18, 20],
+    allowedFps: [24, 25, 48, 50],
+    maxReferenceImages: 2,
+    supportsGenerateAudio: true
   },
   "ltx-2-5-pro": {
     resolutions: ["1280x720", "720x1280", "1920x1080", "1080x1920"],
-    minSeconds: 2,
+    minSeconds: 6,
     maxSeconds: 10,
-    allowedSeconds: [2, 3, 4, 5, 6, 8, 10],
-    supportsSeed: true,
-    maxSeed: 4294967295,
-    allowedFps: [24, 25, 50]
+    allowedSeconds: [6, 8, 10],
+    allowedFps: [24, 25, 50],
+    maxReferenceImages: 2,
+    supportsGenerateAudio: true
   },
   "flux-3": {
     resolutions: ["hd", "fhd"],
     ratios: FLUX_VIDEO_RATIOS,
     minSeconds: 5,
     maxSeconds: 20,
-    safetyTolerance: { minimum: 0, maximum: 4 }
+    safetyTolerance: { minimum: 0, maximum: 4 },
+    safetyToleranceMaxWithImages: 2,
+    maxReferenceImages: 10
   }
 };
 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 EXTENDED_GEMINI_RATIOS = [...COMMON_GEMINI_RATIOS, "1:4", "4:1", "1:8", "8:1"];
 var GEMINI_IMAGE_CONSTRAINTS = {
-  "gemini-2.5-flash-image": { aspectRatios: COMMON_GEMINI_RATIOS, supportsSampling: false },
-  "gemini-3-pro-image": { aspectRatios: COMMON_GEMINI_RATIOS, imageSizes: ["1K", "2K", "4K"], supportsSampling: false },
-  "gemini-3.1-flash-image": { aspectRatios: COMMON_GEMINI_RATIOS, imageSizes: ["1K", "2K", "4K"], supportsSampling: false },
+  "gemini-2.5-flash-image": {
+    aspectRatios: COMMON_GEMINI_RATIOS,
+    supportsSampling: false,
+    maxReferenceImages: 1,
+    referenceImagesInlineDataOnly: true,
+    maxSeed: GEMINI_IMAGE_MAX_SEED
+  },
+  "gemini-3-pro-image": {
+    aspectRatios: COMMON_GEMINI_RATIOS,
+    imageSizes: ["1K", "2K", "4K"],
+    supportsSampling: false,
+    maxReferenceImages: 14,
+    maxSeed: GEMINI_IMAGE_MAX_SEED
+  },
+  "gemini-3.1-flash-image": {
+    aspectRatios: EXTENDED_GEMINI_RATIOS,
+    imageSizes: ["1K", "2K", "4K"],
+    supportsSampling: true,
+    maxReferenceImages: 14,
+    maxSeed: GEMINI_IMAGE_MAX_SEED
+  },
   "gemini-3.1-flash-lite-image": {
-    aspectRatios: [...COMMON_GEMINI_RATIOS, "1:4", "4:1", "1:8", "8:1"],
+    aspectRatios: EXTENDED_GEMINI_RATIOS,
     imageSizes: ["1K"],
-    supportsSampling: true
+    supportsSampling: true,
+    maxReferenceImages: 14,
+    maxSeed: GEMINI_IMAGE_MAX_SEED
   }
 };
 function parseSize(size, model) {
@@ -1316,11 +1368,18 @@ function validateGeminiImageGeneration(model, input) {
     const supported = constraint.imageSizes?.join(", ") ?? "none";
     throw new ApiError("invalid_request", `${model} imageSize must be one of ${supported} (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 (input.seed !== void 0 && (!Number.isInteger(input.seed) || input.seed < 0 || constraint.maxSeed !== void 0 && input.seed > constraint.maxSeed)) {
+    const maximum = constraint.maxSeed === void 0 ? "" : ` no greater than ${constraint.maxSeed}`;
+    throw new ApiError("invalid_request", `seed must be a non-negative integer${maximum}`);
+  }
+  if (input.referenceImageCount !== void 0 && constraint.maxReferenceImages !== void 0 && input.referenceImageCount > constraint.maxReferenceImages) {
+    throw new ApiError("invalid_request", `${model} supports at most ${constraint.maxReferenceImages} reference image${constraint.maxReferenceImages === 1 ? "" : "s"}`);
+  }
+  if (constraint.referenceImagesInlineDataOnly && input.nonDataUriReferenceCount) {
+    throw new ApiError("invalid_request", `${model} reference images must be base64 data URIs (inlineData); fileUri inputs are rejected by this model`);
   }
   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`);
+    throw new ApiError("invalid_request", `${model} supports thinkingLevel, temperature, and topP only on gemini-3.1-flash-image and gemini-3.1-flash-lite-image`);
   }
   if (input.thinkingLevel && !["MINIMAL", "HIGH"].includes(input.thinkingLevel.toUpperCase())) {
     throw new ApiError("invalid_request", "thinkingLevel must be MINIMAL or HIGH");
@@ -1335,6 +1394,24 @@ function validateGeminiImageGeneration(model, input) {
 function validateVideoGeneration(model, input) {
   const constraint = VIDEO_CONSTRAINTS[model.trim()];
   if (!constraint) return;
+  if ((input.imageCount ?? 0) > 0 && (input.firstFrameCount ?? 0) > 0) {
+    throw new ApiError("invalid_request", `${model}: --image and --first-frame are mutually exclusive (reference-to-video vs image-to-video)`);
+  }
+  if (constraint.disallowReferences && (input.imageCount ?? 0) > 0) {
+    throw new ApiError("invalid_request", `${model} supports image-to-video only (single --first-frame image); reference images require grok-imagine-video-1.5`);
+  }
+  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 image${constraint.maxReferenceImages === 1 ? "" : "s"}`);
+  }
+  if (input.firstFrameCount !== void 0 && constraint.maxFirstFrameImages !== void 0 && input.firstFrameCount > constraint.maxFirstFrameImages) {
+    throw new ApiError("invalid_request", `${model} image-to-video supports exactly ${constraint.maxFirstFrameImages} starting image${constraint.maxFirstFrameImages === 1 ? "" : "s"} (--first-frame)`);
+  }
+  if (input.generateAudio !== void 0 && constraint.supportsGenerateAudio === false) {
+    throw new ApiError("invalid_request", `${model} does not support generate_audio`);
+  }
+  if (input.watermark !== void 0 && constraint.supportsWatermark === false) {
+    throw new ApiError("invalid_request", `${model} does not support watermark`);
+  }
   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})`);
   }
@@ -1344,6 +1421,9 @@ function validateVideoGeneration(model, input) {
   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.resolution && (input.imageCount ?? 0) > 0 && constraint.referenceResolutions && !constraint.referenceResolutions.includes(input.resolution.toLowerCase())) {
+    throw new ApiError("invalid_request", `${model} reference-to-video mode supports only ${constraint.referenceResolutions.join(" and ")} (received: ${input.resolution}); ${input.resolution} requires text-to-video or a single --first-frame image`);
+  }
   if (input.seconds !== void 0 && input.resolution) {
     const required = constraint.requiredSecondsByResolution?.[input.resolution.toLowerCase()];
     if (required !== void 0 && input.seconds !== required) {
@@ -1378,9 +1458,12 @@ function validateVideoGeneration(model, input) {
   if (input.fps !== void 0 && (!constraint.allowedFps || !constraint.allowedFps.includes(input.fps))) {
     throw new ApiError("invalid_request", `${model} fps must be one of ${constraint.allowedFps?.join(", ") ?? "none"} (received: ${input.fps})`);
   }
-  if (input.safetyTolerance !== void 0 && (!constraint.safetyTolerance || !Number.isInteger(input.safetyTolerance) || input.safetyTolerance < constraint.safetyTolerance.minimum || input.safetyTolerance > constraint.safetyTolerance.maximum)) {
-    const range = constraint.safetyTolerance ? `${constraint.safetyTolerance.minimum}-${constraint.safetyTolerance.maximum}` : "unsupported";
-    throw new ApiError("invalid_request", `${model} safety_tolerance must be ${range} (received: ${input.safetyTolerance})`);
+  if (input.safetyTolerance !== void 0 && constraint.safetyTolerance) {
+    const ceiling = (input.imageCount ?? 0) > 0 && constraint.safetyToleranceMaxWithImages !== void 0 ? Math.min(constraint.safetyTolerance.maximum, constraint.safetyToleranceMaxWithImages) : constraint.safetyTolerance.maximum;
+    if (!Number.isInteger(input.safetyTolerance) || input.safetyTolerance < constraint.safetyTolerance.minimum || input.safetyTolerance > ceiling) {
+      const withImagesNote = constraint.safetyToleranceMaxWithImages !== void 0 && ceiling !== constraint.safetyTolerance.maximum ? ` while images are attached (text-only allows up to ${constraint.safetyTolerance.maximum})` : "";
+      throw new ApiError("invalid_request", `${model} safety_tolerance must be ${constraint.safetyTolerance.minimum}-${ceiling}${withImagesNote} (received: ${input.safetyTolerance})`);
+    }
   }
   if (input.priority !== void 0 && !constraint.supportsPriority) {
     throw new ApiError("invalid_request", `${model} does not support priority`);
@@ -1406,15 +1489,17 @@ import { join as join2, resolve } from "path";
 import { pipeline } from "stream/promises";
 import { Readable } from "stream";
 var SUCCESS_STATES = /* @__PURE__ */ new Set(["success", "succeeded", "completed", "done", "finish", "finished"]);
-var FAILED_STATES = /* @__PURE__ */ new Set(["failed", "failure", "error", "cancelled", "canceled"]);
+var FAILED_STATES = /* @__PURE__ */ new Set(["failed", "failure", "error", "expired"]);
+var CANCELLED_STATES = /* @__PURE__ */ new Set(["cancelled", "canceled"]);
 var RUNNING_STATES = /* @__PURE__ */ new Set(["running", "processing", "in_progress", "generating"]);
 var PENDING_STATES = /* @__PURE__ */ new Set(["pending", "queued", "submitted", "waiting", "not_start"]);
 function normalizeTaskStatus(raw) {
   const s = String(raw ?? "").toLowerCase();
   if (SUCCESS_STATES.has(s)) return "success";
+  if (CANCELLED_STATES.has(s)) return "cancelled";
   if (FAILED_STATES.has(s)) return "failed";
   if (RUNNING_STATES.has(s)) return "running";
-  if (PENDING_STATES.has(s)) return "pending";
+  if (PENDING_STATES.has(s) || s.startsWith("queued_")) return "pending";
   return "unknown";
 }
 function extractTaskId(body) {
@@ -1441,6 +1526,39 @@ function extractProgress(body) {
   }
   return void 0;
 }
+async function cancelTask(baseUrl, apiKey, taskId) {
+  try {
+    await request({
+      baseUrl,
+      path: `/v1/video/generations/${encodeURIComponent(taskId)}`,
+      method: "DELETE",
+      apiKey
+    });
+  } catch (err) {
+    if (err instanceof ApiError) {
+      const code = err.upstreamCode;
+      if (code === "task_already_running") {
+        throw new ApiError("task_already_running", `\u4EFB\u52A1 ${taskId} \u5DF2\u5F00\u59CB\u8FD0\u884C\uFF0C\u65E0\u6CD5\u53D6\u6D88`, {
+          status: err.status,
+          hint: "\u8FD0\u884C\u4E2D\u7684\u4EFB\u52A1\u4E0D\u53EF\u53D6\u6D88\uFF1B\u7528 focalapi task status " + taskId + " \u8DDF\u8E2A\u5230\u5B8C\u6210\u540E\u4E0B\u8F7D\u4EA7\u7269\u3002"
+        });
+      }
+      if (code === "task_already_finished") {
+        throw new ApiError("task_already_finished", `\u4EFB\u52A1 ${taskId} \u5DF2\u7ED3\u675F\uFF0C\u65E0\u9700\u53D6\u6D88`, {
+          status: err.status,
+          hint: "\u8FD0\u884C focalapi task status " + taskId + " \u67E5\u770B\u7ED3\u679C\uFF1B\u6210\u529F\u540E\u53EF\u4E0B\u8F7D\u4EA7\u7269\u3002"
+        });
+      }
+      if (code === "task_cancel_incomplete") {
+        throw new ApiError("task_cancel_incomplete", `\u4EFB\u52A1 ${taskId} \u5DF2\u53D6\u6D88\u4F46\u6E05\u7406\u672A\u5B8C\u6210`, {
+          status: err.status,
+          hint: "\u8BF7\u91CD\u8BD5\u540C\u4E00\u6761 cancel \u547D\u4EE4\u5B8C\u6210\u6E05\u7406\u3002"
+        });
+      }
+    }
+    throw err;
+  }
+}
 async function fetchTask(baseUrl, apiKey, taskId) {
   let raw;
   try {
@@ -1476,10 +1594,17 @@ async function pollTask(baseUrl, apiKey, taskId, opts) {
     last = await fetchTask(baseUrl, apiKey, taskId);
     opts?.onUpdate?.(last);
     if (last.status === "success") return last;
+    if (last.status === "cancelled") {
+      throw new ApiError("task_cancelled", `\u4EFB\u52A1 ${taskId} \u5DF2\u53D6\u6D88\uFF08\u4E0A\u6E38\u72B6\u6001\uFF1A${last.rawStatus || "cancelled"}\uFF09`, {
+        body: last.raw,
+        hint: "\u4EFB\u52A1\u5DF2\u505C\u6B62\u4E14\u4E0D\u518D\u4EA7\u751F\u8D39\u7528\uFF1B\u5982\u9700\u91CD\u65B0\u751F\u6210\u8BF7\u63D0\u4EA4\u65B0\u4EFB\u52A1\u3002"
+      });
+    }
     if (last.status === "failed") {
-      throw new ApiError("task_failed", `\u4EFB\u52A1 ${taskId} \u5931\u8D25\uFF08\u4E0A\u6E38\u72B6\u6001\uFF1A${last.rawStatus || "unknown"}\uFF09`, {
+      const expired = last.rawStatus?.toLowerCase() === "expired";
+      throw new ApiError("task_failed", expired ? `\u4EFB\u52A1 ${taskId} \u8D85\u8FC7\u6267\u884C\u671F\u9650\uFF08expired\uFF09\uFF0C\u8D39\u7528\u5DF2\u81EA\u52A8\u9000\u8FD8` : `\u4EFB\u52A1 ${taskId} \u5931\u8D25\uFF08\u4E0A\u6E38\u72B6\u6001\uFF1A${last.rawStatus || "unknown"}\uFF09`, {
         body: last.raw,
-        hint: "\u8FD0\u884C focalapi task status " + taskId + " --json \u67E5\u770B\u4E0A\u6E38\u8FD4\u56DE\u8BE6\u60C5\uFF1B\u82E5\u662F\u63D0\u793A\u8BCD\u6216\u53C2\u6570\u95EE\u9898\u8BF7\u8C03\u6574\u540E\u91CD\u8BD5\u3002"
+        hint: expired ? "\u63D0\u4EA4\u72B6\u6001\u672A\u77E5\u4E14\u8D85\u8FC7 10 \u5206\u949F\u5BF9\u8D26\u671F\u9650\u7684\u4EFB\u52A1\u4F1A\u4EE5 expired \u7EC8\u6B62\u5E76\u9000\u6B3E\u3002\u53EF\u67E5\u770B focalapi task status " + taskId + " --json \u540E\u91CD\u65B0\u63D0\u4EA4\u3002" : "\u8FD0\u884C focalapi task status " + taskId + " --json \u67E5\u770B\u4E0A\u6E38\u8FD4\u56DE\u8BE6\u60C5\uFF1B\u82E5\u662F\u63D0\u793A\u8BCD\u6216\u53C2\u6570\u95EE\u9898\u8BF7\u8C03\u6574\u540E\u91CD\u8BD5\u3002"
       });
     }
     if (Date.now() > deadline) {
@@ -1734,7 +1859,9 @@ function registerGen(program) {
       seed: opts.seed,
       thinkingLevel: opts.thinkingLevel,
       temperature: opts.temperature,
-      topP: opts.topP
+      topP: opts.topP,
+      referenceImageCount: opts.image?.length,
+      nonDataUriReferenceCount: opts.image?.filter((source) => !source.trim().startsWith("data:")).length
     });
     const suppliedConfig = parseGenerationConfig(opts.config);
     const suppliedResponseFormat = suppliedConfig.responseFormat;
@@ -1824,7 +1951,7 @@ function registerGen(program) {
       if (res.id) info(`\u4EA4\u4E92 ID\uFF1A${res.id}`);
     }
   });
-  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF1B\u7CBE\u786E\u8303\u56F4\u8FD0\u884C focalapi models get <model> \u67E5\u770B", (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("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9\u30019:16\u3001auto").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--fps <n>", "\u8F93\u51FA\u5E27\u7387\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-tolerance <n>", "\u5B89\u5168\u5BB9\u5FCD\u5EA6\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).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 \u7CFB\u5217\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(
+  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF1B\u7CBE\u786E\u8303\u56F4\u8FD0\u884C focalapi models get <model> \u67E5\u770B", (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("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9\u30019:16\u3001auto").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--fps <n>", "\u8F93\u51FA\u5E27\u7387\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-tolerance <n>", "\u5B89\u5168\u5BB9\u5FCD\u5EA6\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--image <url...>", "\u53C2\u8003\u56FE URL\uFF08Grok \u89C6\u9891\u4E3A reference-to-video \u6A21\u5F0F\uFF0C\u53EF\u591A\u4E2A\uFF09").option("--first-frame <url>", "\u56FE\u751F\u89C6\u9891\u9996\u5E27\u56FE URL\uFF08image-to-video \u6A21\u5F0F\uFF1B\u4E0E --image \u4E92\u65A5\uFF09").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 \u7CFB\u5217\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);
@@ -1838,6 +1965,7 @@ function registerGen(program) {
       }
       if (opts.size) body.size = opts.size;
       if (opts.image) body.images = opts.image;
+      if (opts.firstFrame) body.image = opts.firstFrame;
       if (opts.resolution) metadata.resolution = opts.resolution.toLowerCase();
       if (opts.ratio) metadata.ratio = opts.ratio;
       if (opts.aspectRatio) metadata.ratio = opts.aspectRatio;
@@ -1864,7 +1992,11 @@ function registerGen(program) {
         serviceTier: opts.serviceTier,
         priority: opts.priority,
         executionExpiresAfter: opts.executionExpiresAfter,
-        safetyIdentifier: opts.safetyIdentifier
+        safetyIdentifier: opts.safetyIdentifier,
+        imageCount: opts.image?.length,
+        firstFrameCount: opts.firstFrame ? 1 : 0,
+        generateAudio: opts.generateAudio,
+        watermark: opts.watermark
       });
       if (Object.keys(metadata).length > 0) body.metadata = metadata;
       const created = await withProgress("\u6B63\u5728\u63D0\u4EA4\u89C6\u9891\u4EFB\u52A1", () => request({
@@ -1883,7 +2015,7 @@ function registerGen(program) {
           printJson({ model, task_id: taskId, submitted: true, next_command: `focalapi task status ${taskId} --json` });
         } else {
           process.stdout.write(taskId + "\n");
-          info(`\u4EFB\u52A1\u5DF2\u63D0\u4EA4\u3002\u7EED\u53D6\uFF1Afocalapi task status ${taskId} / focalapi task download ${taskId}`);
+          info(`\u4EFB\u52A1\u5DF2\u63D0\u4EA4\u3002\u7EED\u53D6\uFF1Afocalapi task status ${taskId} / focalapi task download ${taskId}\uFF1B\u6392\u961F\u4E2D\u53EF\u53D6\u6D88\uFF1Afocalapi task cancel ${taskId}`);
         }
         return;
       }
@@ -1909,7 +2041,7 @@ function registerGen(program) {
 
 // src/commands/task.ts
 function registerTask(program) {
-  const task = program.command("task").description("\u4EFB\u52A1\u67E5\u8BE2\u4E0E\u4EA7\u7269\u4E0B\u8F7D\uFF08\u89C6\u9891\u7B49\u4EFB\u52A1\u5236\u80FD\u529B\uFF09");
+  const task = program.command("task").description("\u4EFB\u52A1\u67E5\u8BE2\u3001\u53D6\u6D88\u4E0E\u4EA7\u7269\u4E0B\u8F7D\uFF08\u89C6\u9891\u7B49\u4EFB\u52A1\u5236\u80FD\u529B\uFF09");
   task.command("status").description("\u67E5\u8BE2\u4EFB\u52A1\u72B6\u6001").argument("<task_id>", "\u4EFB\u52A1 ID").action(async (taskId, _opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
@@ -1928,6 +2060,19 @@ function registerTask(program) {
       if (info_.status === "success") {
         info(`\u4EA7\u7269\u4E0B\u8F7D\uFF1Afocalapi task download ${taskId}`);
       }
+      if (info_.status === "pending" || info_.status === "running") {
+        info(`\u5982\u9700\u505C\u6B62\u6392\u961F\u4E2D\u7684\u4EFB\u52A1\uFF1Afocalapi task cancel ${taskId}`);
+      }
+    }
+  });
+  task.command("cancel").description("\u53D6\u6D88\u6392\u961F\u4E2D\u7684\u4EFB\u52A1\uFF08\u8FD0\u884C\u4E2D\u7684\u4EFB\u52A1\u4E0D\u53EF\u53D6\u6D88\uFF1B\u53D6\u6D88\u540E\u8D39\u7528\u81EA\u52A8\u9000\u8FD8\uFF09").argument("<task_id>", "\u4EFB\u52A1 ID").action(async (taskId, _opts, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const auth = resolveAuth(g);
+    await cancelTask(auth.baseUrl, auth.apiKey, taskId);
+    if (g.json) {
+      printJson({ task_id: taskId, status: "cancelled", cancelled: true });
+    } else {
+      info(`\u2713 \u4EFB\u52A1 ${taskId} \u5DF2\u53D6\u6D88`);
     }
   });
   task.command("download").description("\u4E0B\u8F7D\u4EFB\u52A1\u4EA7\u7269\uFF08\u7ECF focalapi \u5185\u5BB9\u4EE3\u7406\uFF0C\u65E0\u9700\u4E0A\u6E38\u7B7E\u540D URL\uFF09").argument("<task_id>", "\u4EFB\u52A1 ID").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", "focalapi-out").action(async (taskId, opts, cmd) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focalapi-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "让任意 AI Agent 直接调用 focalapi 创作模型的命令行工具",
   "type": "module",
   "bin": {

package/skills/focalapi/SKILL.md

@@ -28,6 +28,7 @@ focalapi gen video "<user prompt>" --no-wait -o ./focalapi-out --json
 # Continue an asynchronous video task.
 focalapi task status <task-id> --json
 focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task cancel <task-id> --json   # queued tasks only; cancelled tasks are refunded
 ```
 
 ## Routing table
@@ -37,7 +38,7 @@ focalapi task download <task-id> -o ./focalapi-out --json
 | Generate or edit images; create from reference images | `focalapi gen image` | focalapi-gen |
 | Generate video; animate images or reference media | `focalapi gen video` | focalapi-gen |
 | Select, compare, or inspect model parameters | `focalapi models resolve/get/search` | focalapi-models |
-| Inspect progress or failures; download results | `focalapi task status/download` | focalapi-task |
+| Inspect progress or failures; cancel queued tasks; download results | `focalapi task status/cancel/download` | focalapi-task |
 | Resolve key, sign-in, or 401 issues | `focalapi auth status/login` | focalapi-auth |
 | Inspect quota, usage, or service failures | `focalapi usage/doctor` | focalapi-usage |
 | Provide text assistance explicitly requested by the user | `focalapi chat` | focalapi-chat |

package/skills/focalapi-gen/SKILL.md

@@ -1,50 +1,56 @@
----
-name: focalapi-gen
-version: 2.1.0
-description: "Use FocalAPI for image and video generation, image editing, image-to-video, and reference-media creation. Trigger directly when the user asks to draw, generate or edit an image, create video, or animate media, even without naming FocalAPI. Select a model automatically by default and do not probe models first."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi gen --help"
----
-
-# FocalAPI image and video generation
-
-## Default: select automatically and run once
-
-When the user does not specify a model, run:
-
-```bash
-focalapi gen image "<complete prompt>" -o ./focalapi-out --json
-focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
-```
-
-The CLI selects a default from the live model pool and detailed contracts available to the current key. Do not generate separate samples with a low-cost model, test prompt, or multiple models. Doing so creates unnecessary cost and ambiguity.
-
-## Explicit models and advanced parameters
-
-When the user names a model, read its live contract once:
-
-```bash
-focalapi models get <model-id> --json
-focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./focalapi-out --json
-focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
-```
-
-- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
-- Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
-- Use `--image <url...>` for video reference images. Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
-- Use `--content '<json-array>'` for models such as MiniMax H3, LTX 2.5, and FLUX 3 when the contract requires role-aware media content. LTX also exposes `--fps`; FLUX 3 exposes `--safety-tolerance`.
-- Never copy one model's `ratio`, `aspect_ratio`, `size`, or `resolution` to another model.
-- Use `gen gemini-image` only when the user explicitly selects a native Gemini image model. Continue to use the automatic `gen image` entry point for ordinary requests.
-
-## Complete the result workflow
-
-Synchronous image results contain local absolute paths in `files`; return them directly to the user. For asynchronous results, run the returned `next_command`:
-
-```bash
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-`pending` and `running` are not failures. Keep checking the same `task_id` and never resubmit generation. On failure, read the structured `error.code` and `hint`, and fix only the explicit problem instead of rotating models blindly.
+---
+name: focalapi-gen
+version: 2.2.0
+description: "Use FocalAPI for image and video generation, image editing, image-to-video, and reference-media creation. Trigger directly when the user asks to draw, generate or edit an image, create video, or animate media, even without naming FocalAPI. Select a model automatically by default and do not probe models first."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi gen --help"
+---
+
+# FocalAPI image and video generation
+
+## Default: select automatically and run once
+
+When the user does not specify a model, run:
+
+```bash
+focalapi gen image "<complete prompt>" -o ./focalapi-out --json
+focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
+```
+
+The CLI selects a default from the live model pool and detailed contracts available to the current key. Do not generate separate samples with a low-cost model, test prompt, or multiple models. Doing so creates unnecessary cost and ambiguity.
+
+## Explicit models and advanced parameters
+
+When the user names a model, read its live contract once:
+
+```bash
+focalapi models get <model-id> --json
+focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./focalapi-out --json
+focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
+```
+
+- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
+- Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
+- For video inputs, `--image <url...>` means reference images (Grok 1.5 reference-to-video, capped at 720p and 7 images) and `--first-frame <url>` means image-to-video from a single starting frame. The two flags are mutually exclusive and both are validated against the live contract before submission.
+- Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- Use `--content '<json-array>'` for models such as LTX 2.5, FLUX 3, Kling 3.0, and Vidu Q3 when the contract requires role-aware media content. LTX also exposes `--fps`; FLUX 3 exposes `--safety-tolerance` (0-4 text-to-video, capped at 2 once images are attached).
+- Never copy one model's `ratio`, `aspect_ratio`, `size`, or `resolution` to another model.
+- Use `gen gemini-image` only when the user explicitly selects a native Gemini image model. Continue to use the automatic `gen image` entry point for ordinary requests.
+
+## Complete the result workflow
+
+Synchronous image results contain local absolute paths in `files`; return them directly to the user. For asynchronous results, run the returned `next_command`:
+
+```bash
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+```
+
+`pending` and `running` are not failures. Keep checking the same `task_id` and never resubmit generation. On failure, read the structured `error.code` and `hint`, and fix only the explicit problem instead of rotating models blindly.
+
+Two transient outcomes need no parameter changes:
+
+- `capacity_exhausted` (HTTP 503): the platform queue is full. Retry the same command after roughly 10 seconds; do not switch models or shrink the request.
+- `expired` on a task: submission state stayed unknown past the 10-minute reconciliation window; the charge is refunded automatically. Resubmitting once is correct.

package/skills/focalapi-models/SKILL.md

@@ -1,55 +1,55 @@
----
-name: focalapi-models
-version: 2.1.0
-description: "Select FocalAPI creative models and inspect live parameter contracts. Use when the user does not specify a model, names a model or provider, compares models, or encounters a generation-parameter error. Use resolve to obtain a callable default and never infer capabilities from names or probe models one by one."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi models --help"
----
-
-# FocalAPI model selection
-
-## Shortest path
-
-When the user does not specify a model, do not list every model or rank them yourself:
-
-```bash
-focalapi models resolve image --json
-focalapi models resolve video --json
-```
-
-`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
-
-- `model.id`: the exact ID accepted by generation commands;
-- `endpoint_type`: the generation endpoint verified by model details;
-- `model.supported_params`: available parameters, defaults, enumerations, and ranges;
-- `next_command`: the next command with no guessing required.
-
-Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
-
-## User-selected models
-
-```bash
-focalapi models get <complete-model-id> --json
-```
-
-Search once only when the user provides an incomplete provider or family name:
-
-```bash
-focalapi models search <keyword> --json
-focalapi models get <selected-complete-id> --json
-```
-
-Rules:
-
-1. `models get` is authoritative for endpoints and parameters. A list summary may show only a protocol family and cannot be used to infer modality.
-2. Do not send generation requests to models one by one as an availability test. Discovery and detail queries are read-only preflight checks.
-3. If an explicitly selected model is unavailable, present available candidates or return to `models resolve`; never replace it silently.
-4. Return to the user's original generation task after the query instead of stopping at the model list.
-
-## Current verified creative families
-
-The maintained defaults currently prefer Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images. Video selection currently covers Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, FLUX 3, and MiniMax H3.
-
-These names are routing context, not permission to guess a model ID. Use the exact canonical ID returned by `models resolve` or `models get`. Removed IDs, including the former Veo 3.1 preview models, must not be retried.
+---
+name: focalapi-models
+version: 2.1.0
+description: "Select FocalAPI creative models and inspect live parameter contracts. Use when the user does not specify a model, names a model or provider, compares models, or encounters a generation-parameter error. Use resolve to obtain a callable default and never infer capabilities from names or probe models one by one."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi models --help"
+---
+
+# FocalAPI model selection
+
+## Shortest path
+
+When the user does not specify a model, do not list every model or rank them yourself:
+
+```bash
+focalapi models resolve image --json
+focalapi models resolve video --json
+```
+
+`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
+
+- `model.id`: the exact ID accepted by generation commands;
+- `endpoint_type`: the generation endpoint verified by model details;
+- `model.supported_params`: available parameters, defaults, enumerations, and ranges;
+- `next_command`: the next command with no guessing required.
+
+Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
+
+## User-selected models
+
+```bash
+focalapi models get <complete-model-id> --json
+```
+
+Search once only when the user provides an incomplete provider or family name:
+
+```bash
+focalapi models search <keyword> --json
+focalapi models get <selected-complete-id> --json
+```
+
+Rules:
+
+1. `models get` is authoritative for endpoints and parameters. A list summary may show only a protocol family and cannot be used to infer modality.
+2. Do not send generation requests to models one by one as an availability test. Discovery and detail queries are read-only preflight checks.
+3. If an explicitly selected model is unavailable, present available candidates or return to `models resolve`; never replace it silently.
+4. Return to the user's original generation task after the query instead of stopping at the model list.
+
+## Current verified creative families
+
+The maintained defaults currently prefer Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images. Video selection currently covers Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, and FLUX 3.
+
+These names are routing context, not permission to guess a model ID. Use the exact canonical ID returned by `models resolve` or `models get`. Removed IDs, including the former Veo 3.1 preview models, must not be retried.

package/skills/focalapi-task/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: focalapi-task
-version: 2.0.0
-description: "Continue asynchronous FocalAPI image or video tasks and download their outputs. Use when a generation response contains task_id or next_command, or when the user asks about progress, failure reasons, or result files. Reuse the original task_id and never generate again."
+version: 2.1.0
+description: "Continue asynchronous FocalAPI image or video tasks, cancel queued tasks, and download their outputs. Use when a generation response contains task_id or next_command, or when the user asks about progress, failure reasons, cancellation, or result files. Reuse the original task_id and never generate again."
 metadata:
   requires:
     bins: ["focalapi"]
@@ -15,11 +15,15 @@ After a generation command returns `task_id`, prefer the response's `next_comman
 ```bash
 focalapi task status <task-id> --json
 focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task cancel <task-id> --json
 ```
 
 - `pending` or `running`: this is still the same valid task. Check it later and do not resubmit generation.
 - `success`: run download, verify that the file exists, and return its absolute path to the user.
-- `failed`: show the upstream error summary and hint. Generate again only when an explicit parameter or content issue requires it.
+- `failed`: show the upstream error summary and hint. Generate again only when an explicit parameter or content issue requires it. A raw status of `expired` means the submission state stayed unknown past the reconciliation window; the charge was refunded automatically.
+- `cancelled`: the task was stopped; a cancelled queued task is refunded. Do not download or resubmit unless the user asks for a new attempt.
 - `unknown`: preserve the raw response and run `focalapi doctor --json`; never fabricate a success state.
 
+`task cancel` only works while a task is still queued (`pending`). A 409 `task_already_running` means generation already started and cannot be stopped — keep tracking with `task status`. Cancellation failures return explicit codes (`task_already_finished`, `task_cancel_failed`); follow `error.hint` instead of retrying blindly.
+
 Polling must be bounded. When the user does not ask for blocking wait behavior, report the current status and `task_id`.

package/skills/focalapi-usage/SKILL.md

@@ -19,6 +19,7 @@ focalapi doctor --json
 - For quota, balance, usage, or billing questions, run `usage`.
 - For `missing_api_key` or `invalid_api_key`, route to focalapi-auth.
 - For `insufficient_quota`, run `usage`, explain the shortfall, and do not add funds automatically.
+- For `capacity_exhausted` (HTTP 503), wait about 10 seconds and retry the exact same command; the queue admission gate is full and parameters are not the problem.
 - For `network_error`, `timeout`, or 5xx errors, run `doctor` once and follow `checks[].hint`.
 - For `invalid_request`, return to the live `models get` parameter contract and do not resend the same request.
 - For `upstream_auth_failed`, preserve the request ID and escalate to the service operator; do not ask the user to replace the FocalAPI key.