Poe Provider Integration

Quick Setup (3 Steps)

1. Get Your API Key

# Visit https://poe.com/api while logged in
# Click "Create API Key"
# Copy the key (it starts with poe-)

2. Set Environment Variable

export POE_API_KEY=poe-xxxxx-your-key-here

3. Verify It Works

poe-code auth status

Switching from OpenAI SDK

This is the fastest way to use Poe with existing code:

// ❌ Wrong - OpenAI
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// ✅ Correct - Poe (just add baseURL!)
import OpenAI from 'openai';
const client = new OpenAI({ 
  baseURL: 'https://api.poe.com/v1',
  apiKey: process.env.POE_API_KEY 
});

Python:

# Same pattern - just add base_url
from openai import OpenAI
client = OpenAI(
    base_url="https://api.poe.com/v1",
    api_key=os.environ.get("POE_API_KEY")
)

Model Name Mapping

Poe Code CLI (Essential Tool)

Poe provides a powerful CLI for managing Poe integration:

Core Commands

# Install
npm install -g poe-code

# Check balance
poe-code usage

# View usage history
poe-code usage list --pages 5

# List available models
poe-code models
poe-code models --search claude

# Wrap Claude Code with Poe
poe-code wrap claude

# One-off prompt
poe-code spawn claude "Fix the bug in auth.ts"

# Spawn against GitHub repo
poe-code spawn codex "Review auth module" --cwd github://owner/repo

MCP Server Setup

# Configure Claude Code to use Poe MCP
npx poe-code@latest mcp configure claude-code

# Available MCP tools:
# - generate_text  (query any Poe bot)
# - generate_image
# - generate_video
# - generate_audio

API Endpoints

Responses API (Recommended)

curl -X POST "https://api.poe.com/bot/claude-3-5-sonnet" \
  -H "Poe-API-Key: $POE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Your question"}'

Chat Completions API (OpenAI-compatible)

curl -X POST "https://api.poe.com/v1/chat/completions" \
  -H "Authorization: Bearer $POE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Auth Header by Endpoint

Authentication

API Key (Simplest)

# Environment variable
export POE_API_KEY=poe-xxxxx

# Or use poe-code login (opens browser)
npx poe-code@latest login

OAuth PKCE (For User-Facing Apps)

import { poeOAuth } from 'poe-oauth';

// 1. Create auth URL
const { authorizationUrl } = await poeOAuth.createAuthCode({
  callbackUrl: 'https://yourapp.com/callback'
});
res.redirect(authorizationUrl);

// 2. Exchange code for key
const { key } = await poeOAuth.exchangeCode({ code: req.query.code });

Usage & Billing

Poe uses compute points, not tokens. Monitor usage:

# Check balance
poe-code usage

# View history
poe-code usage list --pages 5

# Filter by model
poe-code usage list --filter claude

Point Costs (Relative)

Error Handling

Quick Reference

401 vs 403

• 401 Unauthorized: Your API key is wrong or expired
• 403 Forbidden: Your subscription doesn't cover this

Retry Pattern

async function retryWithBackoff(fn: () => Promise<Response>, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn();
    if (response.ok) return response;
    if (response.status === 429 || response.status >= 500) {
      await sleep(Math.pow(2, i) * 1000);
      continue;
    }
    throw new Error(`HTTP ${response.status}`);
  }
}

Content Generation

Image Generation

curl -X POST "https://api.poe.com/bot/dalle-3" \
  -H "Poe-API-Key: $POE_API_KEY" \
  -d '{"query": "A sunset over mountains", "image_size": "1024x1024"}'

Sizes: 1024x1024 (square), 1792x1024 (landscape), 1024x1792 (portrait)
Styles: vivid (enhanced), natural (realistic)

Video Generation

curl -X POST "https://api.poe.com/bot/video-generator" \
  -H "Poe-API-Key: $POE_API_KEY" \
  -d '{"query": "Ocean waves crashing"}'

Audio (TTS)

curl -X POST "https://api.poe.com/bot/audio-tts" \
  -H "Poe-API-Key: $POE_API_KEY" \
  -d '{"query": "Hello!", "voice": "alloy"}'

Voices: alloy, echo, fable, onyx, nova, shimmer

Gotchas (Additional)

• OAuth requires subscription: Users need Poe Pro subscription for API access
• Rate limits vary by tier: Check poe-code usage for your limits
• Streaming errors: Wrap in try/catch, handle incomplete streams
• Model availability: Not all models available via API (some web-only)

Reference Files