1
Executar a CLI
Use npx sem instalação global. O pacote publicado requer Node.js 20 ou mais recente.
node --version
npx -y @poyoapi/cli helpPoYo CLIpacote npm disponível
Descubra e execute modelos da PoYo pelo seu terminal.
Pesquise o catálogo em tempo real e consulte Schema sem API Key. Autentique-se quando for transmitir chat, enviar uma geração ou retomar uma tarefa pelo task_id.
$npx -y @poyoapi/cli helpComece a usar a PoYo CLI em três etapas
Execute a CLI e escolha um modelo com models e describe. Adicione uma API Key somente para executar um modelo ou consultar dados da conta.
2
Escolher um modelo
Este exemplo encontra o modelo gpt-image-2 disponível no momento e consulta seu Schema de entrada atualizado e preço público. Nenhum dos dois comandos exige uma chave de API.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Autenticar e executar
Crie uma API Key e execute os três comandos abaixo em ordem. Consulte o preço com describe antes da execução paga; gerações com falha não consomem créditos.
Criar API Key1. Salvar a API Key
Resultado esperado: a CLI solicita a Key sem exibi-la e depois informa keyring ou config como local de armazenamento. Se o gerenciador de credenciais do sistema não estiver disponível, usa o arquivo de configuração PoYo do usuário atual.
npx -y @poyoapi/cli auth login2. Verificar conta e saldo
Resultado esperado: dados da conta e saldo disponível. Um erro 401 significa que a Key está ausente ou é inválida.
npx -y @poyoapi/cli account3. Confirmar o preço e executar
Esta é uma solicitação paga. Um resultado JSON bem-sucedido inclui task_id, status final e arquivos de saída.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonConverta o Schema do modelo em argumentos da CLI
Antes de chat, run ou submit, a CLI lê o Schema do modelo escolhido e converte os campos em argumentos específicos.
Pesquise antes de executar
models lista o catálogo público. describe retorna Schema, protocolos, modo de execução, callback e cobrança.
Esses dois comandos não exigem API Key.
Prompt de geração
Um campo string do Schema é aceito como valor normal de linha de comando.
Opções desconhecidas falham localmente. A validação completa do JSON Schema ainda acontece na API.
Retorne agora e retome depois
submit retorna um task_id imediatamente. task get lê o estado e task wait continua aguardando.
Indicado para vídeo, áudio, 3D e outras tarefas longas.
Controle a saída da CLI
O chat em streaming grava texto ou JSONL em stdout. Comandos sem streaming podem retornar table, JSON, JSONL ou CSV e gravar o resultado em um arquivo.
A CLI usa os mesmos endpoints e a mesma cobrança da REST API.
Escolha o comando certo para cada tarefa
Comandos separados cuidam da descoberta de modelos, chat, geração, retomada de tarefas e ponte MCP local.
~/projects/poyo-demo
# 1. Escolher um modelo
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Entrada de comando gerada
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Autenticar e executar
$ 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 da tarefa
Continue tarefas longas com task_id
A PoYo retorna diretamente o estado público existente da tarefa. Se a CLI atingir o tempo limite ou encerrar, consulte a mesma tarefa em vez de enviá-la novamente.
Um timeout da CLI não cancela a tarefa no backend. Reutilize o mesmo task_id em vez de pagar por uma solicitação duplicada.
Use submit para trabalhos longos
$ 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
Use run para espera limitada
run consulta a cada dois segundos e espera até 90 segundos por padrão.
Use submit para trabalhos longos
Guarde o task_id e use task get ou task wait em outro terminal ou etapa de CI.
Escolha entre CLI, MCP, REST e Skill
Use CLI no terminal e em CI, MCP para chamadas de ferramentas do Agent, REST API em aplicações e Skill para workflows de Agent repetíveis.
PoYo CLI
Desenvolvedores, terminal e CI
Uma pessoa ou script precisa descobrir, executar, retomar e ler códigos de saída.
Instalar CLIMCP
Agents de IA e clientes de código
Um Agent precisa descobrir Schema, preços e ferramentas por uma conexão.
Ver MCPREST API
Aplicações e serviços
Seu produto controla orquestração, streaming, novas tentativas e tráfego.
Abrir docsPoYo Skill
Fluxos de Agent repetíveis
Um Agent precisa de instruções e regras de segurança além das interfaces.
Ver SkillPerguntas sobre a PoYo CLI
Ainda tem dúvida sobre um comando? Falar com o suporte da PoYo→
A PoYo CLI é um cliente de linha de comando orientado pelo catálogo para descobrir e chamar modelos de chat, imagem, vídeo, áudio e 3D da PoYo. Ela lê o Capability Catalog em tempo real, transforma campos Schema em opções de comando e usa os mesmos endpoints da PoYo para execução e status de tarefas.
models e describe leem o Capability Catalog público. Chat, geração, tarefas, conta e execução paga exigem API Key.
run aguarda 90 segundos por padrão. O timeout não cancela a tarefa no backend. Continue com npx -y @poyoapi/cli task wait TASK_ID.
Salve no gerenciador de segredos da CI e exponha como POYO_API_KEY. Fixe @poyoapi/cli@VERSION, solicite --format json e trate qualquer código de saída diferente de zero como falha. Não grave no repositório.
Não. A CLI usa os mesmos endpoints. describe mostra o preço público e account o saldo atual. run e submit são pagos; os créditos só são descontados após uma geração bem-sucedida. 401 indica Key ausente ou inválida e 402 saldo insuficiente.
Uma ponte stdio encaminha JSON-RPC para https://api.poyo.ai/mcp. A execução do modelo continua remota.
Execute seu primeiro modelo da PoYo pelo terminal
Explore primeiro o catálogo público e crie uma API Key quando estiver pronto para executar um modelo.