API Overview

Every BetterWaifu subscription includes API access. Use it to automate your account — Discord bots, batch scripts, n8n workflows, AI agents, and anything else you build. Requests spend the same credits as the website (1 credit per SDXL image by default), with no separate API fee.

Keys, usage, and limits live in the developer console.

Tiers

	Tier 1	Tier 2
Included with	Any active subscription	By application
Concurrency	1 generation at a time	Multiple parallel generations
Batch size	Up to 4 images per request	Sized to your workload
Webhooks	—	Completion callbacks instead of polling
Billing	Your subscription credits	Volume pricing

Tier 2 is for higher-volume use — apps serving other users, agent fleets, content pipelines. Apply in the developer console with a short description of what you're building; accounts are reviewed and set up case by case.

Getting an API key

Sign in at betterwaifu.com with an active subscription
Open the developer console and create a key
Copy it — it is shown only once
Store it in an environment variable (for example BETTERWAIFU_API_KEY)

Keys use the format bw_…. Treat them like passwords — never commit them to git or share them publicly.

Requirements

Requirement	Details
Subscription	Active BetterWaifu subscription
Credits	Sufficient account credits for each generation
Key	API key in `Authorization: Bearer bw_…` header

If your subscription lapses or you run out of credits, API requests return 403 or 402 respectively — same rules as generating on the site.

Base URL

All v1 endpoints live under:

https://betterwaifu.com/api/v1

Authentication

Include your API key on every request:

Authorization: Bearer bw_your_key_here

Endpoints

Method	Path	Description
`GET`	`/api/v1/account`	Credits and subscription status
`GET`	`/api/v1/models`	Generation-enabled model versions
`POST`	`/api/v1/generate`	Submit an image generation job
`GET`	`/api/v1/generate/:id`	Poll job status and retrieve outputs
`GET`	`/api/v1/images`	List your images (ids usable for img2img)

MCP server

The same API is available as an MCP server for AI agents (Claude, Grok, Cursor, and any client that speaks Streamable HTTP MCP), authenticated with the same bw_ keys:

claude mcp add --transport http betterwaifu https://betterwaifu.com/api/mcp \
  --header "Authorization: Bearer $BETTERWAIFU_API_KEY"

It exposes four tools — list_models, generate_image, check_generation, and get_account — that behave exactly like the REST endpoints, including billing and moderation. See betterwaifu.com/mcp for client configs.

Rate limits

10 requests per 10 seconds per user across all v1 endpoints
One active generation at a time per account on Tier 1 — submit returns 429 if a job is already running
Poll every 2–5 seconds — faster polling wastes your rate limit budget
If you hit a 429, check the Retry-After header for how long to wait

Quick start

# 1. List models
curl https://betterwaifu.com/api/v1/models \
  -H "Authorization: Bearer $BETTERWAIFU_API_KEY"
 
# 2. Submit a generation
curl -X POST https://betterwaifu.com/api/v1/generate \
  -H "Authorization: Bearer $BETTERWAIFU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "anime girl, cinematic lighting, detailed illustration",
    "model_version_id": 533326,
    "batch_size": 1
  }'
 
# 3. Poll until complete
curl https://betterwaifu.com/api/v1/generate/job_abc123 \
  -H "Authorization: Bearer $BETTERWAIFU_API_KEY"

Error handling

Responses use JSON with an error field on failure:

{
  "error": "Insufficient credits. Need 1, have 0"
}

Common status codes:

401 — Missing or invalid API key
402 — Insufficient credits
403 — No active subscription, or model not available
429 — Active generation already in progress
500 — Server error

Next steps

Account — Check your credits and subscription
Models — Browse available models
Generate — Request parameters and examples for POST /api/v1/generate
Generation Status — Poll for results