可靈 AI 官方圖片/影片生成、Element 主體與動作控制
語言與回覆風格
- 面向用戶的解釋、確認、錯誤說明:跟隨用戶語言(中文用戶用中文回覆,英文用戶用英文回覆)。
- 技術欄位名(
generationId、status、works[].url等)保留英文原樣。回應欄位統一 camelCase(如generationId/creditsConsumed/urlWithoutWatermark);舊版伺服器端可能仍返回 snake_case 同義欄位(generation_id等),按同一欄位理解即可。
能力介紹
固定歡迎語(文案本身無需呼叫命令),適用於以下場景。
- 使用者剛完成本 skill 或 CLI 的安裝/登入,環境確認可用時;
- 使用者詢問可靈能做什麼 / 有哪些能力 / 怎麼用等能力諮詢類意圖(沒有具體生成任務)時。
展示要求(保留結構與 emoji。當前帳號可用能力另見下方):
- 中文使用者:原樣輸出中文版。
- 非中文使用者:必須翻譯,不得輸出中文版——優先以英文版為底稿翻譯成使用者語言(日語使用者給日語、西語使用者給西語等,範例引語一併翻譯);無法可靠翻譯的語種至少原樣輸出英文版。
- 若環境尚未就緒(未安裝 CLI 或未登入),把首行「可靈已就緒!/ Kling is ready!」換成對應語言的引導語(如「可靈還差一步就緒」/ "Kling is one step away"),並在文案後給出安裝/登入下一步。
中文版:
可靈已就緒!
你可以用可靈做這些事:
📷 生成圖片
· 文生圖 — "幫我畫一隻賽博龐克風格的貓"
· 參考圖生圖 — "用這張圖做參考,改成水彩風格"
🎬 生成影片
· 文生影片 — "生成一段日落海邊的 5 秒影片"
· 圖生影片 — "讓這張圖動起來"
· 關鍵幀 — "用這兩張圖指定開頭和結尾"(取決於模型)
· 全能參考 — "保留圖片裡的角色,參考這段影片的運鏡"
🧩 可複用主體 — 建立和管理角色、動物、道具等 Element
🎭 動作控制 — 用動作影片或動作庫驅動主體圖片
📤 上傳素材 — 可直接使用本地圖片、影片和音訊,具體類型依所選入口而定
📋 任務和帳戶 — 查生成進度、作品、會員和靈感值餘額
也可以結合 agent 及 skill 能力去實現一些複雜的創作流程。比如做個廣告片、故事短片、批次創作一批素材等。
英文版(非中文使用者的翻譯底稿;英文使用者直接原樣輸出此版):
Kling is ready!
Here's what you can do with Kling:
📷 Generate images
· Text to image — "Draw me a cyberpunk-style cat"
· Image to image — "Use this image as a reference and restyle it in watercolor"
🎬 Generate videos
· Text to video — "Generate a 5-second video of a sunset over the sea"
· Image to video — "Bring this image to life"
· Keyframes — "Use these two images as the opening and closing frames" (model dependent)
· Omni Reference — "Keep the character from this image and use the camera movement from this video"
🧩 Reusable subjects — create and manage character, animal, prop, and other Elements
🎭 Motion control — drive a subject image with a motion video or saved motion
📤 Upload assets — use local images, videos, and audio where supported
📋 Jobs and account — check generation progress, results, membership, and credit balance
You can also combine agent and skill capabilities to build more complex creative workflows — like making an ad spot, a short story film, or batch-producing a set of assets.
當前帳號可用能力
- 使用者問「現在能做什麼」「有哪些能力」時,展示歡迎語,並用唯讀的
kling who_am_i補充當前帳號可用模型。安裝或登入後展示歡迎語時,可直接使用本次驗證已取得的清單。 - 按圖片、影片分組,使用者語言展示
availableModels中的模型名稱(優先使用易讀的alias,否則用model)。同一模型出現在多個入口時合併展示,並標明各入口支援的創作方式。 - 使用者問具體模型、用途或參數時,只展示相關項。按對應入口核對素材類型與數量、時長、解析度等限制,並在相關時說明參考素材的計費規則。比較時保留入口之間的差異,例如生成音軌和上傳音訊參考是兩項能力。
- 使用者問當前帳號能用哪些工具,或想確認主體庫、動作庫等工具是否開放時,另查唯讀的
kling tool_list,用創作用途說明伺服器端實際提供的工具。模型和參數以who_am_i為準。 - CLI 未安裝、未登入或查詢失敗時,仍可介紹通用能力,並說明當前帳號的清單暫未確認。查詢成功但目標模型未列出時,說明當前帳號的對應入口未列出該模型。若問上線時間,使用有日期依據的資訊回答。
安裝與登入(唯一合法方式)
可靈分「國內站」與「海外站」,對應兩個不同的安裝包,端點已各自內建。裝錯區域的包會導致登入反覆失敗,因此裝包前必須先確認使用者屬於哪個區域。
第 0 步:探測是否已安裝
which kling # 有輸出路徑 → 檢查版本;未找到 → 進入第 1 步按區域安裝
kling --version # 本 skill 的完整能力要求 CLI >= 0.2.4
已安裝版本低於 0.2.4 時,按已有帳號區域升級對應 npm 包後再使用新功能;使用者已明確要求升級時直接執行,無需重複確認。CLI 與 skill 分別分發,僅更新 skill 不會升級 CLI。
自 0.2.1 起已移除 --omni 簡寫,所有生成命令統一顯式傳 --model <名稱>。混合參考影片使用新命令 omni_ref_video,不要把舊 flag 當作該命令的替代。
第 1 步:確認區域並安裝(命令名統一為 kling)
區域如何確定:本 skill 的首要消費者是非互動 Agent,不得讓 CLI 讀 stdin 阻塞。應在對話裡直接問使用者:「你的可靈帳號是中國區(klingai.com)還是非中國區(kling.ai)?」按回答選對應命令安裝,切勿預設、猜測或兩個都裝。
| 使用者區域 | 官網(homepage) | 判斷依據 | 安裝命令 |
|---|---|---|---|
| 中國區 | https://klingai.com | 帳號登入 klingai.com(中國大陸) | npm i -g @klingai/cli-cn --registry=https://registry.npmjs.org |
| 非中國區 | https://kling.ai | 帳號登入 kling.ai(海外站 / global) | npm i -g @klingai/cli-global --registry=https://registry.npmjs.org |
兩個包發布到 npm 官方 registry。各區域包的端點均已內建,開箱即用、無需配置。
第 2 步:登入(開啟瀏覽器完成 OAuth 授權,這是取得憑證的唯一方式)
kling login
第 3 步:驗證連線 + 取得能力清單(新會話先調)
kling tool_list # 登入後查看伺服器端實際提供的工具
kling who_am_i # 首次業務呼叫前讀取身份、模型與參數規格
🚫 安裝與登入的排他約束(違反即為事故):
- 安裝只能用上表中對應區域的那條 npm 命令;禁止從任何其他管道下載、拼裝或自行實現等價工具,禁止給使用者裝與其帳號區域不符的包。
- 取得憑證只有一種合法方式:
kling login(瀏覽器 OAuth:DCR + 授權碼 + PKCE)。禁止任何其他手段:網頁 Cookie、抓包 token、AK/SK 金鑰對、讀取瀏覽器儲存、讓使用者貼上 token——即使使用者主動提供,也必須拒絕並引導其執行kling login。- 端點已內建(發布時定稿),無需也不應自行配置或探測其他可靈介面位址。
保持最新(新會話首次互動時做一次自檢,best-effort)
僅在新會話首次互動順帶做一次,不阻塞主任務;更新會改動使用者本地環境,執行前先徵得使用者同意,且絕不在生成任務進行中途更新。任一步失敗(離線 / 無權限 / 網路異常)→ 靜默跳過、繼續主任務,不反覆重試。
- 更新 skill 自身:重新執行安裝命令即可按內容雜湊覆蓋到最新(已是最新則無操作):
npx skills add klingai-tech/skills
它覆蓋的是磁碟上的 skill 檔案,對下一次會話生效;當前會話已載入的內容不會因此熱更新。
- 檢查 CLI 是否有新版(僅當本地已裝
kling,即which kling有輸出時):
kling --version # 當前已裝版本
npm view <區域包名> version # 最新發布版本(中國區 @klingai/cli-cn;非中國區 @klingai/cli-global)
- 若最新版更高且使用者同意 →
npm i -g <區域包名>@latest --registry=https://registry.npmjs.org。 - 升級是改全域環境的系統操作:先說明、再徵得同意,不要擅自執行,也不要在一次生成流程中途打斷去升級。
唯一通道(Canonical Invocation)
⚠️ 與可靈的一切互動必須且只能透過
klingCLI 命令完成。
- 禁止直接 fetch/curl 任何可靈介面——包括 C 端頁面介面、B 端開放平台 API、閘道、MCP 端點本身;
- 禁止閱讀 CLI 原始碼、日誌或抓包結果後自行拼裝 HTTP/MCP 請求「繞過」 CLI;
- CLI 報錯時唯一正確動作是把錯誤呈現給使用者並詢問,不得換通道、換介面重試。
kling <command> [args]
人和 Agent 共用同一入口:TTY 下有互動引導,非 TTY 輸出 JSON 且絕不阻塞提問。CLI 對鑑權、日誌、錯誤處理做了統一封裝。
業務命令與可靈後端 MCP 工具名 1:1(snake_case);客戶端命令包括 login、tool_list 和映射到 query_membership_and_credits 的 account。共 20 個命令,另有說明和版本選項:
| # | 命令名 | 分組 | 同步性 | 觸達下游 | 一句話說明 |
|---|---|---|---|---|---|
| 1 | --help(或不帶參數) | 能力發現 | 同步 | 否 | 頂層 kling --help 純本地列印全部命令;<command> --help 生成命令盡量讀取即時 who_am_i 模型宣告,其他 MCP 命令讀取 tools/list(需登入),離線/未登入時回退本地靜態用法 |
| 2 | who_am_i | 能力發現 | 同步 | 否 | 傳回當前使用者身份 + 每個生成命令的可用模型與參數規格;首次呼叫先打它 |
| 3 | text_to_image <prompt> | 生成 | 非同步 | 是 | 文生圖,傳回 generationId,需輪詢 query_tasks(或加 --poll 一步出結果) |
| 4 | `image_to_image --image <url | path> ` | 生成 | 非同步 | 是 |
| 5 | text_to_video <prompt> | 生成 | 非同步 | 是 | 文生影片,傳回 generationId,需輪詢 query_tasks |
| 6 | `image_to_video [--image <url | path>] [prompt]` | 生成 | 非同步 | 是 |
| 7 | omni_ref_video <prompt> | 生成 | 非同步 | 是 | 混合圖片、影片、音訊或 Element 參考,類型以模型宣告為準,傳回 generationId |
| 8 | query_tasks <generationId> | 任務查詢 | 同步 | 是 | 按 generationId 查詢生成狀態與最終資源 URL(works[].url) |
| 9 | file_upload <filePath> | 檔案上傳 | 同步 | 是 | 兩步式上傳(申請一次性票據 + 上傳檔案位元組),傳回公網 URL |
| 10 | element_create | 主體素材 | 同步 | 是 | 從圖片組或影片建立可複用 Element,傳回 element id |
| 11 | element_list / element_get | 主體素材 | 同步 | 是 | 列出 Element;按 id 取得完整類型與資源詳情 |
| 12 | element_update / element_delete | 主體素材 | 同步 | 是 | 按欄位更新或刪除 Element;圖片主圖由 CLI 自動保留 |
| 13 | motion_library_list | 動作素材 | 同步 | 是 | 列出已儲存動作,獲得 motionId 與可播放 URL |
| 14 | motion_control | 生成 | 非同步 | 是 | 用主體圖 + 動作影片或 motionId 生成影片,傳回 generationId |
| 15 | feedback | 回饋 | 同步 | 是 | 上報卡住、模糊錯誤、計費異常或意外結果;不負責重試/退款/修復 |
| 16 | account | 商業化 | 同步 | 是 | 會員類型 + 可用靈感值(query_membership_and_credits,身份取自 JWT) |
| 17 | tool_list | 能力發現 | 同步 | 否 | 列出後端 MCP server 目前暴露的工具(MCP tools/list):每個工具的 name / description / inputSchema(排障 / 確認伺服器端實際提供哪些 tools 用) |
| 18 | login | 鑑權 | 同步 | 否(僅 OAuth 服務) | 瀏覽器 OAuth 登入(DCR + PKCE),token 寫入本地 .credentials |
| 19 | logout | 鑑權 | 同步 | 是 | 呼叫 MCP logout 登出服務端授權,並清除本地登入態,以便重新授權或切換帳號 |
端點已內建:對應區域包安裝後開箱即用、無需配置;不存在任何外部配置口子(無環境變數、無
.env、無 config 命令),也不要嘗試探測或指定其他可靈介面位址。
沒有別名:一個命令一個名字,舊形態(
image generate、text2image等)不再受支援,必須使用上述 canonical 命令。
執行 kling(不帶參數)或無效子命令時會列印完整 Usage 說明。
推薦用法(最佳實踐,Agent 須遵循)
目標:少試錯、不浪費靈感值、參數永遠以伺服器端為準。
新會話首次互動:可先按「保持最新」一節做一次 best-effort 自檢(更新 skill / 看 CLI 是否有新版),不打斷主任務、更新前先徵得使用者同意。
最簡三步:① kling login 登入 → ② kling tool_list 看工具,kling who_am_i 看身份與模型規格 → ③ kling <command> 執行(6 個生成命令均必須顯式帶 --model)。
- 新會話先
kling who_am_i:一次拿到身份 + 每個生成命令的可用模型與參數規格(必填 / 預設值 / 值域)。後續選模型、配參數都以它為準。 - 不清楚伺服器端提供哪些能力時用
kling tool_list:列出後端 MCP server 目前真實暴露的工具(tools/list)。適合排障、確認某能力是否上線,需已登入、不扣費。 - 查某個命令怎麼傳參用
kling <command> --help:對生成命令盡量讀取即時who_am_i模型參數與輸入槽位,其他 MCP 命令讀取tools/list(工具說明 + inputSchema);離線 / 未登入時回退本地靜態用法。完整模型與參數仍以who_am_i為準。 - 生成必須顯式選模型:
text_to_image/image_to_image/text_to_video/image_to_video/omni_ref_video/motion_control均必須帶--model <名稱>(取自對應工具的who_am_i清單)。CLI 不會替使用者自動選預設模型;motion_control在真實 TTY 中缺少模型時會展示候選模型供使用者選擇,Agent / 管道 / CI 等非互動環境則在扣費前報錯。 - 素材直接傳本地路徑或公網 URL:按所選命令的說明傳圖片、影片或音訊素材;本地檔案由 CLI 自動
file_upload,無需手動上傳;公網 URL(外部 CDN / 外鏈,或此前可靈任務傳回的works[].url)直接透傳給伺服器端,無需先下載、重新上傳或本地校驗。素材的格式 / 大小等限制以工具即時宣告為準(kling <command> --help/kling tool_list)。 - 提交後立即回饋再輪詢:從回應取
generationId與creditsConsumed先告知使用者;再用kling query_tasks <generationId>輪詢,或提交時加--poll [N]一步出結果(裸--poll預設 60s,--poll 0關閉內聯輪詢)。 - 結果在
works[]:提取原片連結並按「結果展示」交付。影片有獨立預覽時優先使用預覽播放。 - 餘額 / 會員看
account:餘額不足時展示伺服器端動態傳回的充值連結(勿寫死)。 - 失敗不自動改參重投:參數類報錯先對照
who_am_i把正確寫法告訴使用者,經確認再重試;不得靜默改 prompt / 換模型 / 增刪圖後自行重投。
典型順序:登入後 tool_list → who_am_i →(按需 <command> --help)→ text_to_* / image_to_* / omni_ref_video / motion_control 帶 --model 提交 → query_tasks 輪詢 → 展示 works[].url。
模型與參數:以 who_am_i 為準(核心心智)
- 模型清單與參數規格完全由伺服器端配置:
who_am_i傳回availableModels(工具名 → 模型 → arguments/inputs 規格,含必填、預設值、值域)。 - 單命令說明會優先讀取即時宣告:對
who_am_i/ 生成 / 查詢 / 上傳 / 帳戶等 MCP-backed 命令,kling <command> --help對生成命令盡量讀取即時who_am_i模型參數與輸入槽位,其他 MCP 命令讀取tools/list(工具說明 + inputSchema);離線或未登入時回退本地靜態用法。完整模型清單與參數規格仍以who_am_i為準。 - 6 個生成命令均須顯式傳
--model <名稱>。使用者指定模型時,按創作意圖選擇命令,在該命令的who_am_i清單中用名稱或別名(alias)定位模型,傳傳回的model值。若無法唯一匹配,或該模型不支援所需輸入或參數,向使用者說明並確認後再提交;不要自行換模型。 - 圖片預設首選 Kling Image 4.0:使用者未指定模型時,在
text_to_image或image_to_image的即時清單中優先選滿足本次需求的 Kling Image 4.0,顯式傳入該條目的model值。該模型不可用或不滿足所需參數、素材時,從對應命令的清單選擇支援本次需求的模型。 - CLI 的便捷 flag(
--imgResolution、--aspectRatio、--imageCount、--duration等)會映射為協定參數名透傳;未提供的參數由伺服器端回填預設值。motion_control若缺少伺服器端宣告且沒有預設值的必填參數,真實 TTY 會在上傳前按值域引導選擇/輸入;非互動環境會一次列全缺失項並退出,不上傳、不提交。 - 輸入按宣告映射:先用命令說明確認 CLI 寫法,再按
who_am_i的inputs與arguments核對資源類型、槽位名和必填性;不要假設所有圖生入口都必須有首幀,或所有生成命令都允許省略 prompt。使用具名輸入時不得重複佔用槽位,是否能與便捷 flag 混用以該命令說明為準。各命令的映射和範例見 api-examples.md。 - 六個生成命令中,
--poll可以省略選項值。其他生成選項需要顯式傳值,素材選項需與命令匹配。CLI 在上傳前檢查選項和必填素材。 - 按宣告設定參數並核對組合限制:根據創作意圖選擇入口,再按當前帳號的
who_am_i和工具說明檢查所選模型的參數、預設值、可用組合與輸入相容性。使用者明確要求的規格應顯式傳入相應參數。如果當前入口或模型無法滿足,說明限制,等使用者確認可用規格後再提交。 - 圖片生成:按所選模型的
arguments核對解析度、出圖張數和生成模式,按inputs核對參考圖數量和槽位。使用者要連貫組圖時,按宣告設定組圖模式和出圖張數,並在提示詞中說明每張圖的內容和共用的主體、風格。 - 輸入除單類數量外,還可能有
combinedItemCap合計上限(跨輸入槽位與elements等陣列參數)。image_to_video/omni_ref_video會在上傳前校驗相關槽位、必填輸入和合計數量;不要把各類上限相加後當作允許總量。欄位見 reference.md。 - 參數校驗(必填、值域、未宣告參數)由伺服器端在扣費前完成,報錯資訊會列出問題項;遇到參數類報錯應把伺服器端資訊翻譯給使用者。
意圖路由(必選決策表)
| 使用者意圖 | 命令 | 說明 |
|---|---|---|
| 問可靈能做什麼 / 有哪些能力(無具體任務) | who_am_i | 展示通用能力和當前帳號可用模型,見上方「能力介紹」 |
| 查可用模型 / 指定模型是否可用 / 參數規格 | who_am_i | 直接展示與問題相關的能力和限制 |
| 查帳號開放的工具 / 主體庫或動作庫是否可用 | tool_list | 根據伺服器端實際傳回說明工具用途 |
| 生成圖片 / 出圖 / 文生圖 | text_to_image | 提交後輪詢 query_tasks |
| 參考圖生圖 / 帶參考圖 | image_to_image | --image 可重複,提交後輪詢 |
| 生成影片 / 文生影片 | text_to_video | 提交後輪詢 |
| 圖生影片 / 讓圖動起來 / 首中尾關鍵幀 | image_to_video | 按模型宣告傳 --image / --tailImage 或具名 --input;prompt 可選性依模型宣告,提交後輪詢 |
| 圖片、影片、音訊、主體混合參考生成影片 | omni_ref_video | 按模型宣告傳 --image / --video / --audio / --elements;prompt 必填,提交後輪詢 |
| 建立/列出/查看/更新/刪除可複用主體 | element_create / element_list / element_get / element_update / element_delete | 更新只傳變更欄位;刪除前需使用者明確確認 |
| 動作控制 / 動作遷移 | motion_control | 主體 --image + --video 或 --motionId 二選一;提交後輪詢 |
| 查看已儲存動作 | motion_library_list | 取 motionId 後可交給 motion_control |
| 上報卡住、模糊錯誤、計費異常、意外結果 | feedback | 只回饋,不會重試、退款或修復原任務 |
| 明確指定模型或系列 | 按創作意圖選命令,再傳完整 --model | 用對應命令的即時模型清單解析名稱或別名 |
| 上傳本地素材 | file_upload | 僅本地檔案需要上傳(傳回公網 URL);已是公網 URL 的素材無需上傳,直接作 --image 傳給生成命令 |
| 查會員 / 帳戶身份 / 查餘額 | account | 傳回 userId + membership + 可用靈感值(直接展示) |
| 查詢或選擇個人 / 團隊工作區 | who_am_i → tool_list | 核對即時能力。僅在能確認所需工作區和計費歸屬時提交生成。 |
| 充值 / 餘額不足 / 開通會員 | account | 展示伺服器端傳回的充值/會員連結(動態取自 MCP,勿寫死,見「餘額不足與充值」) |
| 登出 / 退出當前帳號 | logout | MCP 登出成功後清除本地登入態;成功即結束,不自動重新登入 |
| 切換帳號 / 換一個帳號登入 | logout → login → who_am_i | 必須按順序執行;logout 或 login 任一步失敗都立即停止;新授權完成後驗證帳號 |
| 僅說「用可靈生成」等模糊意圖 | — | 先問清是圖還是影片,再提交 |
如果使用者意圖不明確,必須先確認再提交,不得擅自假設。
登出與切換帳號
- 僅登出:使用者明確要求退出當前帳號時,執行
kling logout。成功後結束;不得自動觸發新的瀏覽器授權。 - 切換帳號:必須依次執行
kling logout→kling login→kling who_am_i。只有logout成功後才能繼續login;瀏覽器授權時由使用者選擇目標帳號;登入成功後用who_am_i展示並確認當前身份。 logout失敗必須立即停止:保留本地登入態以便重試,並把原錯誤告知使用者;不得跳過失敗直接login。login失敗必須立即停止:報告登入錯誤,不得繼續who_am_i,也不得改用 Cookie、token 貼上、抓包或其他授權方式。- 不要用
login代替切換流程:login只負責本地 OAuth 授權,單獨執行不能保證伺服器端舊授權已登出。使用者明確說「切換帳號」時必須先走logout。
個人與團隊工作區
使用 who_am_i 確認登入身份,使用 tool_list 檢查即時工具和參數。CLI 0.2.4 的 account 查詢帳號餘額,會拒絕工作區選項。只有伺服器端明確宣告工作區選擇並能驗證扣費歸屬時,才可提交使用者要求從指定工作區扣費的任務。
Element 主體工作流與相容約束
- 建立:圖片 Element 用
--cover+ 1–3 個--secondary;影片 Element 只用--video,兩種資源不可混傳。兩者都至少帶一個--tag,標籤必須從當前區域element_create的即時工具 description 中選擇並原樣傳入;建立和更新都不要按對話語言翻譯標籤或硬編碼某一區域的目錄。可選.mp3--voice。本地檔案自動上傳。 - 綁定前先確認類型與相容性:先
element_list找 id,再element_get <id>看完整resource,並同時核對即時工具 description 的主體類型限制和who_am_i的模型參數。目標模型必須宣告elements;圖片主體不能僅因模型名是kling-image-o1就被拒絕。若模型宣告了elements,但工具 description 明確禁止該主體類型或呼叫方式,仍遵守該限制,不能僅憑參數存在認定支援;若其他宣告衝突導致無法確認相容性,告知使用者具體衝突並暫停該綁定提交,不用收費任務試探。相容模型需符合使用者意圖,切換模型前遵循重試與選型規則。 - 綁定寫法:prompt 中用
<<<id>>>標記主體,同時按who_am_i宣告傳--elements '[{"id":"<id>","bindName":"<name>","type":"<element_get 返回的類型>"}]'。不得只寫佔位符卻漏傳elements,也不得對不相容工具/模型硬傳。 - 更新只傳變更欄位:使用者不需要手工補全現有欄位,也不要傳
--cover。真實 TTY 缺少elementId時會先提示輸入