Poe API Universal Generator

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

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.