Communitygithub.com

kling-cli

Interface oficial de linha de comando para geração de imagens e vídeos da Kling AI, com suporte a elementos reutilizáveis e controle de movimento.

O que é kling-cli?

Este skill fornece uma interface de linha de comando (CLI) para a plataforma Kling AI, permitindo que agentes e usuários gerem imagens e vídeos de forma programática. Ele suporta uma ampla gama de funcionalidades, incluindo geração de texto para imagem/vídeo, imagem para imagem/vídeo, referência omnidirecional (omni_ref_video) e criação de elementos reutilizáveis (personagens, animais, objetos) com controle de movimento. A CLI é o único canal para interagir com os servidores MCP da Kling AI, garantindo autenticação segura via OAuth (PKCE) e tratamento de erros consistente. O skill também inclui comandos para gerenciar tarefas (query_tasks), consultar saldo (account), gerenciar elementos (element_create, element_update, etc.) e enviar feedback. A instalação é feita via npm, com pacotes distintos para os mercados chinês (klingai.com) e global (kling.ai), e a CLI deve ser mantida atualizada para garantir compatibilidade com as capacidades mais recentes do servidor.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/klingai-tech/skills/tree/main

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Kling AI — Geração Oficial de Imagens/Vídeos, Controle de Elementos e Movimento

Idioma e Estilo de Resposta

  • Explicações, confirmações e mensagens de erro voltadas ao usuário: seguir o idioma do usuário (usuários brasileiros respondam em português, usuários japoneses em japonês, etc.).
  • Nomes de campos técnicos (generationId, status, works[].url, etc.) permanecem em inglês. Campos de resposta em camelCase unificado (ex.: generationId / creditsConsumed / urlWithoutWatermark); versões antigas do servidor podem ainda retornar snake_case (generation_id, etc.), que devem ser tratados como o mesmo campo.

Introdução de Capacidades

Mensagem de boas-vindas fixa (não requer chamada de comando), aplicável nas seguintes situações:

  1. Quando o usuário acaba de instalar/configurar este skill ou CLI e o ambiente está confirmado como funcional;
  2. Quando o usuário pergunta o que a Kling pode fazer / suas capacidades / como usar (intenção de consulta sobre capacidades, sem tarefa de geração específica).

Requisitos de exibição (manter estrutura e emojis. As capacidades disponíveis na conta atual estão listadas abaixo):

  • Usuários não falantes de português: Devem receber a mensagem no seu idioma — use a versão em inglês como base e traduza para o idioma do usuário (ex.: usuário japonês recebe em japonês, usuário espanhol em espanhol, incluindo as citações de exemplo); para idiomas em que a tradução não seja confiável, pelo menos exiba a versão em inglês.
  • Se o ambiente ainda não estiver pronto (CLI não instalado ou não logado), substitua a primeira linha "Kling is ready!" por uma mensagem de orientação no idioma apropriado (ex.: "Kling is one step away"), seguida das instruções de instalação/login.

Versão em inglês (base para tradução; falantes de inglês recebem esta versão diretamente):

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.

Capacidades disponíveis na conta atual

  • Quando o usuário perguntar "o que posso fazer agora" ou "quais capacidades você tem", exiba a mensagem de boas-vindas e, em seguida, use kling who_am_i (somente leitura) para complementar com os modelos disponíveis na conta atual. Ao exibir a mensagem de boas-vindas após a instalação ou login, pode usar diretamente a lista obtida nesta verificação.
  • Agrupar por imagem/vídeo, e exibir os nomes dos modelos de availableModels no idioma do usuário (preferir o alias legível, senão usar model). Se um mesmo modelo aparecer em múltiplas entradas, deve ser exibido uma vez, indicando os métodos de criação suportados em cada uma.
  • Quando o usuário perguntar sobre um modelo específico, uso ou parâmetro, exiba apenas os itens relevantes. Verificar os limites de tipo e quantidade de assets, duração, resolução, etc., e informar as regras de cobrança para assets de referência quando aplicável. Ao comparar, manter as diferenças entre as entradas, como capacidade de gerar trilha sonora vs. fazer upload de áudio de referência.
  • Se o usuário perguntar quais ferramentas a conta atual tem disponíveis, ou quiser confirmar se a biblioteca de elementos ou a biblioteca de movimentos está aberta, use kling tool_list (somente leitura) para obter as ferramentas reais fornecidas pelo servidor. Modelos e parâmetros prevalecem com base em who_am_i.
  • Se a CLI não estiver instalada, logada ou a consulta falhar, ainda é possível apresentar as capacidades gerais, explicando que a lista da conta atual não foi confirmada. Se a consulta for bem-sucedida, mas o modelo desejado não estiver listado, informar que a entrada correspondente na conta atual não inclui esse modelo.

Instalação e Login (Única Maneira Válida)

A Kling possui um "site doméstico" (China) e um "site internacional", que correspondem a dois pacotes de instalação distintos, com endpoints já embutidos. Instalar o pacote errado causará falhas repetidas de login. Portanto, antes de instalar, é obrigatório confirmar a região do usuário.

Passo 0: Verificar se já está instalado

which kling   # Se exibir um caminho → verificar versão; se não encontrado → ir para o Passo 1 e instalar conforme a região
kling --version   # A capacidade completa deste skill requer CLI >= 0.2.4

Se a versão instalada for inferior a 0.2.4, atualize o pacote npm correspondente à região da conta antes de usar novos recursos; se o usuário explicitamente solicitar a atualização, execute-a diretamente sem confirmar novamente. A CLI e o skill são distribuídos separadamente; atualizar apenas o skill não atualiza a CLI.

Desde a versão 0.2.1, a abreviação --omni foi removida; todos os comandos de geração devem usar explicitamente --model <nome>. O comando para referência omnidirecional de vídeo é omni_ref_video, não use a flag antiga como substituto.

Passo 1: Confirmar a região e instalar (nome do comando unificado como kling)

Como determinar a região: O principal consumidor deste skill é um agente não interativo, não é permitido que a CLI leia stdin e bloqueie. Pergunte diretamente ao usuário na conversa: "Sua conta Kling é da região da China (klingai.com) ou da região fora da China (kling.ai)?" Use o comando correspondente para instalar. Nunca assuma, adivinhe ou instale ambos.

Região do usuárioSite (homepage)Base de determinaçãoComando de instalação
Chinahttps://klingai.comConta faz login em klingai.com (China continental)npm i -g @klingai/cli-cn --registry=https://registry.npmjs.org
Fora da Chinahttps://kling.aiConta faz login em kling.ai (site internacional/global)npm i -g @klingai/cli-global --registry=https://registry.npmjs.org

Ambos os pacotes são publicados no registro oficial do npm. Os endpoints de cada pacote regional já estão embutidos, funcionam prontos para uso, sem necessidade de configuração.

Passo 2: Fazer login (abrir o navegador para concluir a autorização OAuth — é a única forma de obter credenciais)

kling login

Passo 3: Verificar a conexão + obter a lista de capacidades (nova sessão deve chamar primeiro)

kling tool_list   # Após o login, ver as ferramentas reais fornecidas pelo servidor
kling who_am_i    # Antes da primeira chamada de negócio, ler a identidade, modelos e especificações de parâmetros

🚫 Restrição de instalação e login (violação é considerada incidente):

  • A instalação só pode usar o comando npm correspondente à região do usuário na tabela acima; é proibido baixar, montar ou implementar ferramentas equivalentes de qualquer outra fonte, e é proibido instalar um pacote que não corresponda à região da conta do usuário.
  • A obtenção de credenciais tem apenas uma maneira válida: kling login (OAuth via navegador: DCR + código de autorização + PKCE). É proibido qualquer outro método: cookies de site, captura de token, pares de chave AK/SK, leitura de armazenamento do navegador, ou fazer o usuário colar um token — mesmo que o usuário forneça ativamente, deve recusar e orientá-lo a executar kling login.
  • Os endpoints já estão embutidos (definidos no momento da publicação), não é necessário nem permitido configurar ou descobrir outros endereços de API da Kling.

Manter-se Atualizado (Auto-verificação na primeira interação de uma nova sessão, best-effort)

Apenas na primeira interação de uma nova sessão, faça uma auto-verificação sem bloquear a tarefa principal; atualizações alteram o ambiente local do usuário, obtenha consentimento do usuário antes de executar, e nunca interrompa uma tarefa de geração em andamento para atualizar. Se qualquer passo falhar (offline / sem permissão / erro de rede) → ignore silenciosamente e continue a tarefa principal, sem repetir.

  1. Atualizar o skill em si: Execute novamente o comando de instalação para sobrescrever com a versão mais recente (se já estiver na mais recente, nenhuma operação):
npx skills add klingai-tech/skills

Isso sobrescreve o arquivo do skill no disco, entrando em vigor na próxima sessão; o conteúdo já carregado na sessão atual não será atualizado a quente.

  1. Verificar se há uma nova versão da CLI (apenas se o kling local já estiver instalado, ou seja, which kling exibir algo):
kling --version                                   # Versão atualmente instalada
npm view <nome_do_pacote_regional> version          # Versão mais recente publicada (China: @klingai/cli-cn; Global: @klingai/cli-global)
  • Se a versão mais recente for superior e o usuário concordar → npm i -g <nome_do_pacote_regional>@latest --registry=https://registry.npmjs.org.
  • Atualizar é uma operação de sistema que altera o ambiente global: explique primeiro, depois obtenha consentimento, não execute por conta própria, nem interrompa um fluxo de geração em andamento.

Invocação Canônica (Único Canal)

⚠️ Toda interação com a Kling deve, e só pode, ser feita através do comando kling CLI.

  • É proibido usar fetch/curl diretamente para qualquer endpoint da Kling — incluindo endpoints de página C, API de plataforma aberta B, gateway, ou o próprio endpoint MCP;
  • É proibido ler o código-fonte da CLI, logs ou resultados de captura de rede para montar manualmente requisições HTTP/MCP "contornando" a CLI;
  • Quando a CLI reportar um erro, a única ação correta é apresentar o erro ao usuário e perguntar, não tente outro canal ou endpoint.
kling <comando> [argumentos]

Humanos e agentes usam a mesma entrada: em TTY, há orientação interativa; em não-TTY, a saída é JSON e nunca bloqueia pedindo entrada. A CLI encapsula autenticação, logs e tratamento de erros de forma unificada.

Os comandos de negócio têm correspondência 1:1 com os nomes de ferramentas MCP do backend (snake_case); comandos do cliente incluem login, tool_list e account (que mapeia para query_membership_and_credits). Total de 20 comandos, além de opções de ajuda e versão:

#Nome do comandoGrupoSincroniaAlcance downstreamDescrição resumida
1--help (ou sem argumentos)Descoberta de capacidadesSíncronoNãokling --help imprime todos os comandos localmente; <comando> --help para comandos de geração tenta ler a declaração de modelo em tempo real de who_am_i, outros comandos MCP leem tools/list (requer login), e em caso de offline/não logado, fallback para o uso estático local
2who_am_iDescoberta de capacidadesSíncronoNãoRetorna a identidade do usuário atual + modelos disponíveis e especificações de parâmetros para cada comando de geração; chame primeiro em uma nova sessão
3text_to_image <prompt>GeraçãoAssíncronoSimTexto para imagem, retorna generationId, requer polling com query_tasks (ou adicione --poll para resultado direto)
4`image_to_image --image <urlcaminho> `GeraçãoAssíncronoSim
5text_to_video <prompt>GeraçãoAssíncronoSimTexto para vídeo, retorna generationId, requer polling com query_tasks
6`image_to_video [--image <urlcaminho>] [prompt]`GeraçãoAssíncronoSim
7omni_ref_video <prompt>GeraçãoAssíncronoSimReferência mista de imagem, vídeo, áudio ou Element, tipos conforme declaração do modelo, retorna generationId
8query_tasks <generationId>Consulta de tarefasSíncronoSimConsulta o status de geração e URLs finais dos recursos (works[].url) com base no generationId
9file_upload <caminho_do_arquivo>Upload de arquivosSíncronoSimUpload em duas etapas (solicitar ticket único + enviar bytes do arquivo), retorna URL pública
10element_createAssets de elementoSíncronoSimCria um Element reutilizável a partir de um conjunto de imagens ou um vídeo, retorna o element id
11element_list / element_getAssets de elementoSíncronoSimLista Elements; obtém detalhes completos do tipo e recursos por id
12element_update / element_deleteAssets de elementoSíncronoSimAtualiza por campo ou deleta um Element; a imagem principal é preservada automaticamente pela CLI
13motion_library_listAssets de movimentoSíncronoSimLista movimentos salvos, obtendo motionId e URL reproduzível
14motion_controlGeraçãoAssíncronoSimUsa imagem de elemento + vídeo de movimento ou motionId para gerar vídeo, retorna generationId
15feedbackFeedbackSíncronoSimReporta travamento, erro ambíguo, anomalia de cobrança ou resultado inesperado; não é responsável por repetir/reembolsar/corrigir
16accountComercialSíncronoSimTipo de assinatura + créditos disponíveis (query_membership_and_credits, identidade obtida do JWT)
17tool_listDescoberta de capacidadesSíncronoNãoLista as ferramentas atualmente expostas pelo servidor MCP backend (MCP tools/list): name / description / inputSchema de cada ferramenta (para depuração / confirmar quais ferramentas o servidor realmente oferece)
18loginAutenticaçãoSíncronoNão (apenas serviço OAuth)Login OAuth via navegador (DCR + PKCE), token salvo localmente em .credentials
19logoutAutenticaçãoSíncronoSimChama MCP logout para revogar a autorização no servidor e limpa o estado de login local, permitindo reautorização ou troca de conta

Endpoints já embutidos: os pacotes de cada região funcionam prontos para uso após instalação, sem necessidade de configuração; não existe nenhum ponto de configuração externo (sem variáveis de ambiente, sem .env, sem comando de configuração), e não tente descobrir ou especificar outros endereços de API da Kling.

Sem aliases: um comando, um nome. Formas antigas (image generate, text2image, etc.) não são mais suportadas; use os comandos canônicos acima.

Executar kling (sem argumentos) ou com um subcomando inválido imprime a ajuda completa de uso.


Uso Recomendado (Melhores Práticas que o Agente Deve Seguir)

Objetivo: menos tentativas e erros, não desperdiçar créditos, parâmetros sempre baseados no servidor.

Primeira interação de uma nova sessão: Pode primeiro fazer uma auto-verificação best-effort conforme a seção "Manter-se Atualizado" (atualizar skill / verificar nova versão da CLI), sem interromper a tarefa principal, e obtendo consentimento antes de atualizar.

Três passos mínimos: ① kling login → ② kling tool_list para ver ferramentas, kling who_am_i para ver identidade e especificações de modelo → ③ kling <comando> para executar (todos os 6 comandos de geração devem usar explicitamente --model).

  1. Em uma nova sessão, sempre comece com kling who_am_i: Obtenha identidade + modelos disponíveis e especificações de parâmetros (obrigatórios / valores padrão / faixas de valores) para cada comando de geração. Use como base para selecionar modelos e configurar parâmetros.
  2. Quando não souber quais capacidades o servidor fornece, use kling tool_list: Lista as ferramentas reais atualmente expostas pelo servidor MCP backend (tools/list). Útil para depuração e confirmar se uma capacidade está no ar, requer login, não consome créditos.
  3. Para verificar os parâmetros de um comando, use kling <comando> --help: Para comandos de geração, tenta ler os parâmetros e slots de entrada do modelo em tempo real de who_am_i; outros comandos MCP leem tools/list (descrição da ferramenta + inputSchema); em caso de offline/não logado, fallback para o uso estático local. A especificação completa do modelo e parâmetros ainda prevalece com base em who_am_i.
  4. Geração deve selecionar modelo explicitamente: text_to_image / image_to_image / text_to_video / image_to_video / omni_ref_video / motion_control devem usar --model <nome> (obtido da lista do who_am_i para a ferramenta correspondente). A CLI não seleciona automaticamente um modelo padrão; motion_control em TTY real, se faltar modelo, exibirá modelos candidatos para o usuário escolher; em ambientes não interativos (agente / pipeline / CI), reportará erro antes de cobrar.
  5. Assets podem ser passados como caminho local ou URL pública: Passe imagens, vídeos ou áudio de acordo com a ajuda do comando selecionado; arquivos locais são automaticamente submetidos a file_upload pela CLI, sem necessidade de upload manual; URLs públicas (CDN externo / link externo, ou works[].url retornado por tarefas anteriores da Kling) são passadas diretamente para o servidor, sem necessidade de download, re-upload ou verificação local. Limites de formato/tamanho dos assets seguem a declaração da ferramenta em tempo real (kling <comando> --help / kling tool_list).
  6. Após submeter, informe imediatamente o resultado e depois faça polling: Extraia generationId e creditsConsumed da resposta e informe ao usuário; então use kling query_tasks <generationId> para polling, ou adicione --poll [N] no momento da submissão para obter o resultado diretamente (--poll padrão 60s, --poll 0 desativa o polling inline).
  7. Resultados em works[]: Extraia o link da mídia original e entregue conforme "exibição de resultados". Se o vídeo tiver uma prévia independente, priorize a reprodução da prévia.
  8. Saldo / assinatura use account: Quando o saldo for insuficiente, exiba o link de recarga retornado dinamicamente pelo servidor (não hardcode).
  9. Em caso de falha, não mude parâmetros automaticamente e re-submeta: Se for um erro de parâmetro, primeiro compare com who_am_i e informe a sintaxe correta ao usuário, obtendo confirmação antes de repetir; não altere silenciosamente o prompt / troque de modelo / adicione ou remova imagens e re-submeta.

Ordem típica: Após o login, faça tool_list → who_am_i → (se necessário, <comando> --help) → text_to_* / image_to_* / omni_ref_video / motion_control com --model → polling com query_tasks → exibir works[].url.


Modelos e Parâmetros: Prevalece o who_am_i (Mentalidade Central)

  • Lista de modelos e especificações de parâmetros são totalmente configuradas pelo servidor: who_am_i retorna availableModels (nome da ferramenta → modelo → especificações de arguments/inputs, incluindo obrigatórios, valores padrão e faixas de valores).
  • A ajuda de um comando individual tentará ler a declaração em tempo real: Para comandos com suporte MCP (who_am_i / geração / consulta / upload / conta, etc.), kling <comando> --help para comandos de geração tenta ler o modelo e os parâmetros de entrada em tempo real de who_am_i; outros comandos MCP leem tools/list (descrição da ferramenta + inputSchema); em caso de offline ou não logado, fallback para o uso estático local. A lista completa de modelos e especificações de parâmetros ainda prevalece com base em who_am_i.
  • Todos os 6 comandos de geração devem usar explicitamente --model <nome>. Quando o usuário especificar um modelo, escolha o comando adequado à intenção de criação e, na lista do who_am_i para esse comando, localize o modelo pelo nome ou alias (alias) e passe o valor model retornado. Se não for possível uma correspondência única, ou se o modelo não suportar as entradas ou parâmetros necessários, explique ao usuário e confirme antes de submeter; não troque de modelo por conta própria.
  • Para imagens, a preferência padrão é Kling Image 4.0: Se o usuário não especificar um modelo, na lista em tempo real de text_to_image ou image_to_image, priorize o Kling Image 4.0 que atenda às necessidades atuais e passe explicitamente o valor model dessa entrada. Se esse modelo não estiver disponível ou não suportar os parâmetros/assets necessários, selecione um modelo da lista do comando correspondente que suporte as necessidades atuais.
  • Flags convenientes da CLI (--imgResolution, --aspectRatio, --imageCount, --duration, etc.) são mapeadas para nomes de parâmetros do protocolo e passadas diretamente; parâmetros não fornecidos serão preenchidos com valores padrão pelo servidor. Para motion_control, se faltarem parâmetros obrigatórios sem valor padrão declarados pelo servidor, em TTY real, a CLI guiará a seleção/entrada com base na faixa de valores antes do upload; em ambientes não interativos, listará todos os itens ausentes de uma vez e sairá, sem fazer upload ou submeter.
  • Mapeie entradas conforme a declaração: Primeiro, use a ajuda do comando para confirmar a sintaxe da CLI; depois, verifique os tipos de recurso, nomes de slots e obrigatoriedade de acordo com inputs e arguments do who_am_i. Não presuma que todas as entradas de imagem para vídeo devem ter um primeiro frame ou que todos os comandos de geração permitem omitir o prompt. Ao usar entradas nomeadas, não ocupe slots repetidamente; verifique se é possível combiná-las com flags convenientes usando a ajuda do comando. O mapeamento e exemplos de cada comando estão em api-examples.md.
  • Entre os seis comandos de geração, --poll pode omitir o valor da opção. Outras opções de geração precisam ser passadas explicitamente com valor, e as opções de assets devem corresponder ao comando. A CLI verifica as opções e os assets obrigatórios antes do upload.
  • Defina parâmetros conforme a declaração e verifique as restrições de combinação: Selecione a entrada com base na intenção criativa e, em seguida, verifique os parâmetros, valores padrão, combinações disponíveis e compatibilidade de entrada do modelo selecionado de acordo com o who_am_i da conta atual e a descrição da ferramenta. Especificações explicitamente solicitadas pelo usuário devem ser passadas como parâmetros correspondentes. Se a entrada ou modelo atual não puder atender, explique as limitações e aguarde o usuário confirmar as especificações viáveis antes de submeter.
  • Geração de imagens: Verifique a resolução, número de imagens e modo de geração de acordo com arguments do modelo selecionado; verifique o número de imagens de referência e slots de acordo com inputs. Se o usuário quiser um conjunto coerente de imagens, defina o modo de conjunto e o número de imagens conforme a declaração, e especifique o conteúdo de cada imagem e os elementos/estilo compartilhados no prompt.
  • Além dos limites por tipo, pode haver um limite total combinado (combinedItemCap) (através de slots de entrada e parâmetros de array como elements). image_to_video / omni_ref_video verificam os slots relevantes, entradas obrigatórias e quantidade total antes do upload; não some os limites de cada tipo para obter o total permitido. Campos estão em reference.md.
  • A validação de parâmetros (obrigatórios, faixa de valores, parâmetros não declarados) é feita pelo servidor antes de cobrar; a mensagem de erro listará os itens problemáticos. Em caso de erro de parâmetro, traduza a informação do servidor para o usuário.

Roteamento de Intenções (Tabela de Decisão Obrigatória)

Intenção do usuárioComandoDescrição
Perguntar o que a Kling pode fazer / quais capacidades (sem tarefa específica)who_am_iExibir capacidades gerais e modelos disponíveis na conta atual, conforme seção "Introdução de Capacidades" acima
Consultar modelos disponíveis / se um modelo específico está disponível / especificações de parâmetroswho_am_iExibir diretamente as capacidades e limitações relevantes à pergunta
Consultar ferramentas abertas na conta / se a biblioteca de elementos ou de movimentos está disponíveltool_listExplicar a finalidade da ferramenta com base no retorno real do servidor
Gerar imagens / criar imagens / texto para imagemtext_to_imageSubmeter e depois fazer polling com query_tasks
Imagem de referência para imagem / com imagem de referênciaimage_to_image--image pode ser repetido, submeter e depois fazer polling
Gerar vídeo / texto para vídeotext_to_videoSubmeter e depois fazer polling
Imagem para vídeo / animar uma imagem / keyframes de início, meio e fimimage_to_videoPassar --image / --tailImage ou --input nomeado conforme declaração do modelo; prompt opcional depende da declaração; submeter e depois fazer polling
Vídeo com referência mista de imagem, vídeo, áudio e elementoomni_ref_videoPassar --image / --video / --audio / --elements conforme declaração do modelo; prompt obrigatório; submeter e depois fazer polling
Criar/listar/visualizar/atualizar/deletar elementos reutilizáveiselement_create / element_list / element_get / element_update / element_deleteAtualizar apenas campos alterados; antes de deletar, obter confirmação explícita do usuário
Controle de movimento / transferência de movimentomotion_controlElemento --image + --video ou --motionId (um dos dois); submeter e depois fazer polling
Ver movimentos salvosmotion_library_listApós obter motionId, pode ser passado para motion_control
Reportar travamento, erro ambíguo, anomalia de cobrança, resultado inesperadofeedbackApenas feedback; não repete, reembolsa ou corrige a tarefa original
Especificar explicitamente um modelo ou sérieEscolher o comando com base na intenção criativa e passar --model completoUsar a lista de modelos em tempo real do comando correspondente para interpretar nome ou alias
Fazer upload de assets locaisfile_uploadApenas arquivos locais precisam de upload (retorna URL pública); assets que já são URLs públicas não precisam de upload, podem ser passados diretamente como --image para o comando de geração
Consultar assinatura / identidade da conta / saldoaccountRetorna userId + membership + créditos disponíveis (exibir diretamente)
Consultar ou selecionar espaço de trabalho pessoal / de equipewho_am_i → tool_listVerificar capacidades em tempo real. Submeter geração apenas quando o espaço de trabalho e a cobrança puderem ser confirmados.
Recarga / saldo insuficiente / ativar assinaturaaccountExibir link de recarga/assinatura retornado pelo servidor (obtido dinamicamente do MCP, não hardcode, veja "Saldo insuficiente e recarga")
Sair / deslogar da conta atuallogoutApós logout bem-sucedido no MCP, limpar estado de login local; após sucesso, encerrar; não fazer login automaticamente
Trocar de conta / fazer login com outra contalogout → login → who_am_iExecutar sequencialmente; se logout ou login falharem em qualquer etapa, parar imediatamente; após nova autorização, verificar a conta
Apenas dizer "use a Kling para gerar" e intenções ambíguas—Primeiro pergunte se é imagem ou vídeo, depois submeta

Se a intenção do usuário não for clara, confirme antes de submeter; nunca presuma.

Sair e Trocar de Conta

  • Apenas sair: Quando o usuário solicitar explicitamente sair da conta atual, execute kling logout. Após o sucesso, encerre; não dispare automaticamente uma nova autorização do navegador.
  • Trocar de conta: Execute sequencialmente kling logout → kling login → kling who_am_i. Somente após logout bem-sucedido, prossiga para login; na autorização do navegador, o usuário seleciona a conta de destino; após o login bem-sucedido, use who_am_i para exibir e confirmar a identidade atual.
  • Se logout falhar, pare imediatamente: Mantenha o estado de login local para tentar novamente e informe o erro ao usuário; não pule a falha e vá direto para login.
  • Se login falhar, pare imediatamente: Informe o erro de login; não prossiga para who_am_i e não use cookies, token colado, captura de pacote ou outros métodos de autorização.
  • Não use login como substituto do fluxo de troca: login apenas faz autorização OAuth local; executá-lo isoladamente não garante que a autorização antiga no servidor foi revogada. Quando o usuário disser explicitamente "trocar de conta", o fluxo deve começar com logout.

Espaços de Trabalho Pessoais e de Equipe

Use who_am_i para confirmar a identidade logada e tool_list para verificar ferramentas e parâmetros em tempo real. O comando account da CLI 0.2.4, ao consultar o saldo da conta, rejeitará a opção de espaço de trabalho. Submeta tarefas com cobrança em um espaço de trabalho específico apenas se o servidor declarar explicitamente a seleção do espaço de trabalho e puder verificar a cobrança.

Fluxo de Trabalho com Element e Restrições de Compatibilidade

  1. Criação: Elements de imagem usam --cover + 1–3 --secondary; Elements de vídeo usam apenas --video, não misture os dois tipos. Ambos devem incluir pelo menos uma --tag, e as tags devem ser selecionadas da descrição da ferramenta em tempo real de element_create para a região atual e passadas exatamente como estão; não traduza as tags com base no idioma da conversa nem hardcode a lista de uma região. Opcionalmente, pode incluir um --voice no formato .mp3. Arquivos locais são enviados automaticamente.
  2. Antes de vincular, confirme o tipo e a compatibilidade: Primeiro, use element_list para encontrar o id; depois, element_get <id> para ver o resource completo e, simultaneamente, verifique as restrições de tipo de elemento na descrição da ferramenta em tempo real e os parâmetros do modelo em who_am_i. O modelo de destino deve declarar elements; um Element de imagem não deve ser rejeitado apenas porque o nome do modelo é kling-image-o1. Se o modelo declarar elements, mas a descrição da ferramenta proibir explicitamente aquele tipo de elemento ou forma de uso, essa restrição deve ser respeitada; não conclua que é suportado apenas porque o parâmetro existe. Se houver conflitos entre declarações e não for possível confirmar a compatibilidade, informe o usuário sobre o conflito específico e suspenda a tentativa de vinculação; não use uma tarefa paga para testar. O modelo compatível deve estar alinhado com a intenção do usuário e, antes de trocar, siga as regras de repetição e seleção de modelo.
  3. Sintaxe de vinculação: No prompt, use <<<id>>> para marcar o Element; simultaneamente, passe --elements '[{"id":"<id>","bindName":"<name>","type":"<tipo retornado por element_get>"}]' conforme a declaração de who_am_i. Não escreva apenas o placeholder e esqueça de passar elements, nem force o uso em ferramentas/modelos incompatíveis.
  4. Ao atualizar, passe apenas os campos alterados: O usuário não precisa preencher manualmente os campos existentes; também não passe --cover. Em TTY real, se elementId estiver faltando, o sistema solicitará entrada antes de prosseguir.

...

[truncado para tradução]

Habilidades Relacionadas