Docs

1. 1. Create an account

   Sign up and create an API key from Console → API Keys.

2. 2. Point the OpenAI SDK at Promptoll

   # OpenAI SDK
   from openai import OpenAI
   client = OpenAI(base_url="https://api.promptoll.com/v1", api_key="zai_•••")
   
   # Anthropic SDK
   from anthropic import Anthropic
   client = Anthropic(base_url="https://api.promptoll.com", api_key="zai_•••")

3. 3. Pick a model — or let us pick

   client.chat.completions.create(
       model="gpt-4o",          # or "auto", "quality"
       messages=[{"role": "user", "content": "hi"}],
   )

API keys are prefixed with zai_. Create and manage them in Console → API Keys.

Promptoll also speaks the Anthropic Messages API. Use your zai_ key with the official anthropic SDK or Claude Code — no proxy, no wrapper needed.

Python — anthropic SDK

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.promptoll.com",
    api_key="zai_•••",            # your Promptoll key
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

# Streaming
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Claude Code

Set these env vars in your project root or shell profile, then restart Claude Code:

export ANTHROPIC_BASE_URL=https://api.promptoll.com
export ANTHROPIC_API_KEY=zai_•••

Tool use, multi-turn, and streaming are fully supported. Billing works the same as other models.

Fully compatible with the OpenAI Chat Completions API. Drop Promptoll's base_url into any existing OpenAI SDK integration.

All media endpoints share the same base URL and API key as chat. Same OpenAI SDK — just call the matching method.

from openai import OpenAI
client = OpenAI(base_url="https://api.promptoll.com/v1", api_key="zai_•••")

# Embeddings
resp = client.embeddings.create(model="text-embedding-3-small", input="Hello world")
vec = resp.data[0].embedding          # list of floats

# Audio transcription
with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)
print(result.text)

# Text-to-speech — streams mp3 to disk
with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="alloy", input="Welcome to Promptoll!",
) as response:
    response.stream_to_file("output.mp3")

# Image generation
img = client.images.generate(
    model="dall-e-3", prompt="a futuristic city at night", n=1, size="1024x1024"
)
print(img.data[0].url)

import time, httpx

BASE = "https://api.promptoll.com/v1"
H = {"Authorization": "Bearer zai_•••"}

# 1) Create the job  (seconds MUST be a string: "4" | "8" | "12")
job = httpx.post(f"{BASE}/videos", headers=H, json={
    "model": "sora-2",
    "prompt": "a dog running on the beach at sunset",
    "seconds": "4",
    "size": "720x1280",
}).json()
vid = job["id"]                       # -> "video_xxx", status: "queued"

# 2) Poll until completed  (queued -> in_progress -> completed)
while True:
    job = httpx.get(f"{BASE}/videos/{vid}", headers=H).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(5)

# 3) Download the result
if job["status"] == "completed":
    r = httpx.get(f"{BASE}/videos/{vid}/content", headers=H)
    open("out.mp4", "wb").write(r.content)

Prices are per 1 million tokens. Pass the exact model ID in the model field. Each model lists its sweet spot — pick by use case, not just price.

★ Recommended for most users in this tier

Instead of a model ID, pass one of the special routing keywords:

• Promptoll automatically retries non-streaming upstream calls once on transient failures (5xx, 429, timeouts, connection errors) with ~250ms jittered backoff. You don't need your own retry layer for blips — but adding exponential backoff for repeated 5xx/429 from us is still recommended.
• Streaming requests are NOT auto-retried — once bytes are sent we can't safely re-issue. Most OpenAI-compatible SDKs handle stream-restart on their side; rely on that.
• We never retry 4xx (except 429): 400/401/403/422 mean the payload is wrong, retrying just wastes a round trip.
• Pass X-Request-ID: <your-id> on every call (8–64 chars, [A-Za-z0-9_-]). We echo it back in the response and write it into our backend logs — so when something fails you can hand us the ID and we can grep down to the exact request.

curl https://api.promptoll.com/v1/chat/completions \
  -H "Authorization: Bearer zai_•••" \
  -H "X-Request-ID: my-app-req-7f3a92c1" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'

# response includes:
# X-Request-ID: my-app-req-7f3a92c1   ← echoed back, save this for debugging

Pass stream=True for SSE. Promptoll forwards every chunk unchanged and bills on the final usage event.

client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Count to 10"}],
    stream=True,
)

When your requests share a long repeated prefix (system prompt, few-shot examples, document context), providers can cache that prefix and charge a fraction of the normal input price. Promptoll detects cache hits automatically and passes the discount through to your bill.

Support by provider

Enabling caching with Claude (explicit)

Claude is the only provider that requires explicit opt-in. Add cache_control to the blocks you want cached — typically the system prompt or long document context. Subsequent calls that share the same prefix hit the cache.

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.promptoll.com",
    api_key="zai_•••",
)

# First call: writes the system prompt to cache (cache_creation_input_tokens > 0)
# Subsequent calls with the same system prompt: reads from cache (cache_read_input_tokens > 0)
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "You are a helpful assistant. " + "<your long system prompt here>",
        "cache_control": {"type": "ephemeral"},   # mark this block for caching
    }],
    messages=[{"role": "user", "content": "Hello!"}],
)

usage = message.usage
print(f"input tokens:          {usage.input_tokens}")
print(f"cache write tokens:    {usage.cache_creation_input_tokens}")   # only on first call
print(f"cache read tokens:     {usage.cache_read_input_tokens}")       # on cache-hit calls
print(f"output tokens:         {usage.output_tokens}")

Reading cache stats from the response

All providers surface cache information in the usage object. The exact field names differ by provider, but Promptoll normalises them:

# OpenAI SDK (GPT / DeepSeek / Grok / Kimi — all normalised to the same field)
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "hi"}],
)
cached   = resp.usage.prompt_tokens_details.cached_tokens   # 0 when not cached
uncached = resp.usage.prompt_tokens - cached
print(f"cache hit: {cached} tokens  ({cached / resp.usage.prompt_tokens * 100:.0f}%)")

All errors return a JSON body: {"error": {"message": "...", "type": "...", "code": "..."}}

curl https://api.promptoll.com/v1/chat/completions \
  -H "Authorization: Bearer zai_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'