# API Plaza — full integration reference for AI agents

API Plaza is an OpenAI-compatible aggregation gateway: one base URL and one API key for
text, image, and video models from multiple upstream vendors.

## Connection

- Base URL: https://api.apiplaza.ai/v1
- Auth: `Authorization: Bearer <API_PLAZA_KEY>` — self-serve signup at https://admin.apiplaza.ai/register
- Compatibility: fully OpenAI-compatible. Use the official OpenAI SDK (python/node/go/etc.);
  change only base_url and model ids. Streaming (SSE), function/tool calling, multi-turn
  context, and vision content parts pass through unchanged.

## Endpoints

- POST /v1/chat/completions — chat. Params: model, messages, stream, tools, temperature, top_p, max_tokens.
- POST /v1/images/generations — synchronous image generation. Params: model, prompt, size, n. Returns image URLs.
- POST /v1/videos — create an async video task. Params: model, prompt, seconds, image_urls (image-to-video where supported).
- GET  /v1/videos/{task_id} — poll task status: queued → processing → completed. Poll interval ≥2s.
- GET  /v1/videos/{task_id}/content — fetch the finished video file.
- GET  /v1/models — live model list (OpenAI shape).
- GET  https://api.apiplaza.ai/catalog — full catalog with public prices (the same dataset that meters billing).
- POST https://api.apiplaza.ai/estimate — price a call before sending. Body: {model, input_tokens, output_tokens} or {model, generations, seconds}. Returns USD total.
- GET  https://api.apiplaza.ai/status — live gateway status.
- GET  https://api.apiplaza.ai/openapi.json — OpenAPI 3.1 spec (?lang=en|zh).

## Models

The live list is at /v1/models and /catalog — always prefer fetching it over hardcoding.
Families currently include OpenAI (gpt-5, chatgpt-4o-latest, gpt-image-2, sora-2),
Anthropic (claude-opus-4-5, claude-sonnet-4-5), Google (gemini-3-pro-preview, gemini-2.5-flash,
gemini-3-pro-image-preview), DeepSeek (deepseek-v3.2), Zhipu (glm-4.6), ByteDance
(doubao-seedream-5-0-lite, doubao-seedance-2.0), Kuaishou (kling-v3).

## Billing

- Pay-as-you-go, billed in USD (CNY shown on the site is a reference price at the console top-up rate).
- LLMs per 1M tokens (input/output priced separately); images per generation; video by duration tier.
- Failed requests are never billed. No monthly fee, no minimum spend. Balance never expires.

## Errors

OpenAI-style JSON: {"error": {"message", "type", "code"}}.
- 401 — key missing/invalid: check the Authorization header and key status.
- 402/403 — insufficient balance or key limits: top up in the console or widen the key's scope.
- 429 — rate limited: retry with exponential backoff.
- 5xx — gateway/upstream fault: not billed; retry and check https://apiplaza.ai/status.html

## Quickstart (python)

```python
from openai import OpenAI
client = OpenAI(api_key="<API_PLAZA_KEY>", base_url="https://api.apiplaza.ai/v1")
r = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": "hello"}])
print(r.choices[0].message.content)
```

## Agent-ready config snippets

- CLAUDE.md snippet: https://apiplaza.ai/assets/agent/CLAUDE-apiplaza.md
- .cursorrules: https://apiplaza.ai/assets/agent/cursorrules-apiplaza.txt
- AGENTS.md: https://apiplaza.ai/assets/agent/AGENTS-apiplaza.md

Human docs: https://apiplaza.ai/docs.html · Support: support@apiplaza.ai