poyo-ai-models

PoYo AI Models

Use the production Capability Catalog as the source of truth. Never invent model IDs or parameters.

Choose the integration

1. Prefer hosted MCP at https://api.poyo.ai/mcp.
2. After discovery, prefer ?models=MODEL_A,MODEL_B when a small strongly typed tool set is useful. Use ?categories=... only for bounded exploration, and never combine both filters.
3. Use npx @poyoapi/mcp for clients that only support stdio.
4. Use npx @poyoapi/cli for chat SSE or when MCP is unavailable. On Windows shells, inline --input '{...}' JSON is often broken by quoting; pass schema fields as flags such as --prompt "..." --resolution 1K, or write the JSON to a file and use --input-file.
5. Mark Skill executions with _request_source: "skill" in MCP or --request-source skill in CLI.

Keep POYO_API_KEY in the environment or system keyring. Never put it in prompts, query strings, committed files, or retained shell history. If the CLI reports an invalid key, run npx @poyoapi/cli auth status: an environment POYO_API_KEY takes priority over the key saved by auth login.

Inspect tools/list on the selected connection before calling a tool. A filtered connection exposes model-specific tools and poyo_check_job; generic execution tools such as poyo_submit_job are available on the unfiltered /mcp connection. The same rule applies to stdio --models and --categories filters.

Execute

1. Restate the desired modality, model constraints, inputs, output requirements, and budget.
2. Search the catalog and inspect the selected model's schema and pricing.
3. Validate every input against that schema.
4. For chat, use the model-specific tool on a filtered connection or poyo_chat on the unfiltered connection; use CLI poyo chat MODEL --stream only when incremental output is required.
5. For generation or moderation on a filtered connection, call the model-specific tool with _wait_seconds: 0 for video, 3D, music, or other long work. On the unfiltered connection, use poyo_submit_job for long work or poyo_run_model for short generation. Never call a generic execution tool that is absent from tools/list.
6. Treat queued and running as incomplete. Poll with poyo_check_job until succeeded or failed.
7. Report model ID, final status, credits, output URLs or structured output, and any partial or failed result.