API Overview

BetterWaifu offers two API products for different use cases. Most subscribers want the Personal Access API. The Developer API is for teams building products on top of BetterWaifu and requires an application.

Personal Access API

Use this to automate your own BetterWaifu account — Discord bots, batch scripts, n8n workflows, personal tooling, and anything else where you are the end user.

Who it's for: Subscribers automating their own workflow.

Access: Available to any subscriber with an active plan. No application required.

Billing: Uses the same credits as the website (1 credit per SDXL image by default). No separate API fee.

Typical uses:

• Discord bots that generate images for you
• Scripts that batch-generate from a prompt list
• Personal integrations with creative tools you already use

Getting a personal access key

1. Sign in at betterwaifu.com with an active subscription
2. Open Personal Access API to create keys
3. Create a personal access key and copy it — it is shown only once
4. 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

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

Developer API

Use this when you are building an application for other people — a companion app, character tool, game integration, or any product where your users (not just you) consume BetterWaifu generation.

Who it's for: Teams and developers shipping third-party products.

Access: Application required. Developer API access is reviewed on a case-by-case basis.

Billing: Separate from subscriber credits (details provided on approval). Not the same as the Personal Access API.

Typical uses:

• Apps where your users generate images through your UI
• Commercial products that embed BetterWaifu models
• High-volume or multi-tenant integrations

How to apply

The Developer API is not yet self-serve. To request access, email developers@betterwaifu.com with:

• Your app URL
• A short description of your use case
• Expected volume and how end users will interact with generation

Our team will follow up if your application is a fit.

Until you are approved, use the Personal Access API only for automating your own account — not for production apps serving other users.

Which API should I use?

Base URL (Personal Access API)

All Personal Access API endpoints live under:

https://betterwaifu.com/api/v1

Authentication

Include your personal access key on every request:

Authorization: Bearer bw_your_key_here

Endpoints

Rate limits

• 10 requests per 10 seconds per user across all v1 endpoints
• One active generation at a time per account — 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