1
Verifica o teu ambiente e executa a CLI
É necessário o Node.js 20 ou superior. Se node --version mostrar v20 ou superior, executa a CLI diretamente com o npx, sem instalação global.
node --version
npx -y @poyoapi/cli helpPoYo CLIpacote npm disponível
Todos os modelos PoYo — a partir do teu terminal, dos teus scripts e dos teus agents.
Consulta os schemas de entrada e os preços públicos dos modelos atualmente disponíveis no Catálogo PoYo em tempo real, sem chave de API. Só precisas de uma chave quando executares um modelo. Se uma tarefa demorar mais do que o tempo que a CLI espera, continua a verificá-la com o mesmo task_id.
$npx -y @poyoapi/cli helpTrês passos da descoberta ao resultado
Sem instalação global. Verifica o Node.js, inspeciona o modelo, autentica-te e conclui a tua primeira execução.
2
Encontra e inspeciona um modelo
Este exemplo encontra o modelo gpt-image-2 atualmente disponível e depois lê o respetivo Schema de entrada em tempo real e o preço público. Nenhum dos comandos requer chave de API.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Inicia sessão, verifica e executa
Cria uma chave de API e depois conclui, por ordem, os três comandos abaixo. Confirma o preço com describe antes da execução paga; as gerações que falham não consomem créditos.
Criar chave de API1. Guarda a tua chave de API
Esperado: a CLI pede a chave sem a mostrar no ecrã e indica keyring ou config como local de gravação. Se o armazenamento de credenciais do sistema não estiver disponível, recorre ao teu ficheiro de configuração do PoYo.
npx -y @poyoapi/cli auth login2. Verifica a conta e o saldo
Esperado: os dados da conta e o saldo disponível. Um 401 significa que a chave não existe ou é inválida.
npx -y @poyoapi/cli account3. Confirma o preço e executa
Este é um pedido pago. Um resultado JSON bem-sucedido inclui o task_id, o estado final e os ficheiros de saída.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonCriada para workflows multimodais reais
O Catálogo em tempo real indica à CLI que modelos existem, que entradas aceitam, durante quanto tempo as tarefas são acompanhadas e que formato de saída os scripts recebem.
Pesquisa antes de executar
models lista o catálogo público. describe devolve o Schema exato, os protocolos suportados, o modo de execução, o suporte de callbacks e os metadados de faturação de um modelo.
Estes dois comandos não requerem chave de API.
O Schema transforma-se em flags de comando
A CLI lê o Schema em tempo real de cada modelo e expõe os respetivos campos como opções de linha de comandos específicas desse modelo.
As flags de modelo desconhecidas falham localmente. A validação de campos obrigatórios e a validação completa do JSON Schema continuam a ser feitas na API.
Submete uma vez e continua pelo task_id
submit devolve de imediato um task_id. task get lê o estado atual, enquanto task wait continua a consultar até à conclusão ou ao timeout.
Prefere submit para vídeo, áudio, 3D e outras tarefas de longa duração.
Saída estruturada para scripts e CI
Escolhe a saída em tabela para pessoas; utiliza JSON, JSONL ou CSV para scripts e CI. Os comandos sem streaming também podem gravar os resultados num ficheiro.
Utiliza --output FILE com comandos sem streaming. O texto em streaming e o JSONL ficam no stdout.
Como é uma sessão PoYo real
Explora o catálogo público, inspeciona as entradas e o preço atuais de um modelo e depois pede uma saída estruturada para os teus scripts.
~/projects/poyo-demo
# 1. Encontra e inspeciona um modelo
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Inspeciona o Schema em tempo real
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Inicia sessão, verifica e executa
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
"task_id": "task_7f31b2",
"status": "succeeded",
"files": ["https://storage.poyo.ai/.../image.png"]
}Ciclo de vida da tarefa
As tarefas longas não têm de recomeçar do zero
Submete uma só vez trabalho de vídeo, áudio, 3D e outras tarefas de longa duração. Guarda o task_id e continua a aguardar a partir de outro terminal ou de outro passo de CI.
Um timeout da CLI não cancela a tarefa no backend. Continua com o mesmo task_id em vez de submeteres o mesmo trabalho outra vez.
Utiliza submit quando o terminal não deve esperar
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format jsontask_id task_7f31b2
$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format jsonstatus succeeded
Utiliza run quando 90 segundos chegam
run verifica a tarefa de dois em dois segundos e aguarda até 90 segundos por predefinição. Podes definir outro timeout.
Utiliza submit quando o terminal não deve esperar
Copia o task_id devolvido por submit e substitui TASK_ID no comando wait. Podes continuar a partir de outro terminal ou de outro passo de CI.
Utiliza a interface certa para quem chama
Usa a CLI para pessoas e scripts de shell, o MCP para chamadas de ferramentas de agents, a REST dentro de aplicações e o Skill para dar a um agent passos PoYo reutilizáveis e regras de segurança.
PoYo CLI
Programadores, terminais e CI
Uma pessoa ou um script de shell precisa de descobrir modelos, executá-los, retomar tarefas e reagir aos códigos de saída do processo.
Instalar a CLIMCP
Agents de IA e clientes de programação
Um agent deve descobrir schemas, preços e ferramentas de execução através de uma única ligação.
Ver MCPAPI REST
Aplicações e serviços
A tua aplicação precisa de controlo HTTP direto sobre pedidos, streaming, repetições e callbacks.
Abrir documentaçãoPoYo Skill
Workflows de agents repetíveis
Um agent precisa de passos operacionais reutilizáveis e de regras de segurança em conjunto com o acesso por CLI, MCP ou REST.
Ver SkillPerguntas frequentes sobre a PoYo CLI
Ainda tens dúvidas sobre um comando? Contacta o suporte do PoYo→
A PoYo CLI é um cliente de linha de comandos para descobrir e chamar os modelos de chat, imagem, vídeo, áudio e 3D do PoYo. Lê as definições atuais dos modelos a partir do Catálogo de capacidades público, transforma os campos do Schema em opções de comando e utiliza os mesmos endpoints da API PoYo para a execução e o estado das tarefas.
models e describe leem o Catálogo de capacidades público sem credenciais. Os comandos de chat, geração, tarefas, conta e execução paga requerem uma chave de API.
run espera 90 segundos por predefinição. Um timeout interrompe a consulta local, mas não cancela a tarefa no backend. Continua com npx -y @poyoapi/cli task wait TASK_ID.
Guarda a chave no gestor de segredos do teu CI e expõe-a como POYO_API_KEY. Fixa @poyoapi/cli@VERSION para execuções reprodutíveis, pede --format json e trata qualquer saída diferente de zero como falha. Nunca coloques credenciais no histórico de comandos nem em ficheiros do repositório.
Não. A CLI chama os mesmos endpoints. describe mostra o preço público do modelo selecionado e account mostra o teu saldo atual. run e submit são pagos; os créditos só são deduzidos quando uma geração é bem-sucedida. Um 401 significa que a chave não existe ou é inválida, enquanto um 402 significa que a conta não tem créditos suficientes.
Executa uma ponte stdio que reencaminha mensagens JSON-RPC para https://api.poyo.ai/mcp. A execução dos modelos continua no serviço remoto do PoYo.
Código aberto. Pronta a usar em qualquer terminal.
A CLI, com licença MIT, está publicada no npm e é desenvolvida no GitHub. Explora primeiro o Catálogo público e cria uma chave de API quando estiveres pronto para executar um modelo.