poe-api-universal-generator

name	poe-api-universal-generator
description	Use when making universal Poe API requests with a POE_API_KEY for LLM chat plus image, video, and audio generation, including routing, retries, and reproducible outputs.

Poe Universal Request Generator

Overview

This skill provides one workflow for Poe multimodal requests.

It supports:

• LLM requests via OpenAI-compatible Poe endpoints.
• Image generation via direct media endpoint.
• Video generation via direct media endpoint.
• Audio generation via direct media endpoint.

When to Use

Use this skill when:

• You need one Poe API workflow for LLM and media requests.
• You have or can set POE_API_KEY.
• You need request routing by mode: llm, image, video, or audio.
• You need stable retries and reproducible output records.

Do not use this skill when:

• You do not have API key access.
• The task requires private bot access not supported by Poe API.

Doc Evidence

This skill is aligned with official Poe docs and model API pages:

• https://creator.poe.com/docs/external-applications/openai-compatible-api
• https://creator.poe.com/docs/external-applications/external-application-guide?bot_name=Nano-Banana-2
• https://poe.com/Nano-Banana-2/api
• https://poe.com/Veo-3.1/api
• https://poe.com/Lyria-3/api

Reference files:

• Doc notes
• Models directory
• LLM flows
• Media flows
• Parameter mapping
• Error handling

Prerequisites

1. Create a Poe API key at https://poe.com/api/keys.
2. Set environment variable:
   • PowerShell: $env:POE_API_KEY = "<your_key>"
3. Ensure account has subscription or add-on points for paid model calls.
4. Install dependencies with uv sync from this folder.

Mode Routing

Mode	Endpoint	Example model
llm	/v1/chat/completions (or /v1/responses)	Claude-Sonnet-4.6
image	/v1/images	nano-banana-2
video	/v1/videos	veo-3.1
audio	/v1/audio	lyria-3

Media reliability rule:

• Use stream=False for image, video, and audio bot calls.

Quickstart

Universal request script:

uv run scripts/poe_request_orchestrator.py --mode image --model nano-banana-2 --prompt "Sleeping fox under aurora, cinematic lighting" --out "outputs/fox.json"

Video example:

uv run scripts/poe_request_orchestrator.py --mode video --model veo-3.1 --prompt "A skier in the Alps" --params '{"duration":"6s","resolution":"1080p"}' --out "outputs/video.json"

Audio example:

uv run scripts/poe_request_orchestrator.py --mode audio --model lyria-3 --prompt "Ambient synthwave loop" --out "outputs/audio.json"

LLM example:

uv run scripts/poe_request_orchestrator.py --mode llm --model Claude-Sonnet-4.6 --prompt "Summarize the latest build status" --out "outputs/llm.json"

Backward-compatible image wrapper:

uv run scripts/generate_nano_banana_image.py --prompt "A cat in a hat" --aspect-ratio "4:3" --seed 42 --out "outputs/cat.json"

OpenAI-Compatible Notes

If your app already uses OpenAI SDK with Poe base URL:

• Set base_url to https://api.poe.com/v1
• Set api_key to POE_API_KEY
• Keep n fixed to 1.
• Pass custom bot parameters through extra_body.
• For media bots, prefer stream=False.

Operational Guardrails

• On 429/503/529, honor retry headers and apply exponential backoff with jitter.
• Log request id headers when available for support diagnostics.
• Never print full API keys in logs.
• Prefer official bots when consuming user-owned API keys.

Output Expectations

• Raw API response should be saved for reproducibility.
• If output URL(s) are returned, download in a separate explicit step if required by your workflow.
• Record mode, prompt, model, and parameter set used for each request.

Troubleshooting

• 401 authentication_error: invalid or missing POE_API_KEY.
• 402 insufficient_credits: insufficient subscription/add-on points.
• 404 not_found_error: incorrect endpoint or model id.
• 429 rate_limit_error: throttle and retry with backoff.

Governance Checklist

After major edits to this skill:

1. Run python .agents/skills/skill-creator/scripts/quick_validate.py .agents/skills/poe-api-universal-generator.
2. Run script syntax checks for all files in scripts/.
3. Update lockfile parity if this skill is tracked in skills-lock.json.

Files in This Skill

• references/poe-doc-notes.md: high-level evidence notes from official docs.
• references/models-directory.md: practical model ids by mode.
• references/llm-flows.md: chat and responses usage patterns.
• references/media-flows.md: image/video/audio direct endpoint patterns.
• references/parameter-mapping.md: common custom parameter patterns.
• references/error-handling.md: retries, error types, and support diagnostics.
• scripts/poe_request_orchestrator.py: universal route and request helper.
• scripts/generate_nano_banana_image.py: compatibility wrapper for image-only calls.