# Poe API Universal Generator

> 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.

- Skill: `wedsamuel1230/poe-api-universal-generator` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add wedsamuel1230/poe-api-universal-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wedsamuel1230/poe-api-universal-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wedsamuel1230 (https://skillmd.com/u/wedsamuel1230)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wedsamuel1230/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](references/poe-doc-notes.md)
- [Models directory](references/models-directory.md)
- [LLM flows](references/llm-flows.md)
- [Media flows](references/media-flows.md)
- [Parameter mapping](references/parameter-mapping.md)
- [Error handling](references/error-handling.md)

## 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:

```bash
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:

```bash
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:

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

LLM example:

```bash
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:

```bash
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.