Generate

Submit a new image generation request. Returns a job ID that you can use to poll for the result.

Endpoint

POST /api/v1/generate

Authentication

Requires a valid API key in the Authorization header.

Authorization: Bearer bw_your_api_key_here

Request Body

Field	Type	Required	Default	Description
`prompt`	string	Yes	-	The image prompt (max 2000 characters)
`negative_prompt`	string	No	`""`	What to avoid in the generation
`model_version_id`	number	Yes	-	Model ID from GET /api/v1/models
`width`	number	No	`832`	Image width in pixels
`height`	number	No	`1216`	Image height in pixels
`batch_size`	number	No	`1`	Number of images to generate (1-4)
`steps`	number	No	`30`	Number of sampling steps
`cfg_scale`	number	No	`7`	CFG scale (guidance strength)
`sampler`	string	No	`"euler_a"`	Sampling method
`seed`	number	No	random	Seed for reproducibility
`loras`	array	No	-	Up to 4 `{ model_version_id, strength }` entries — ids from the `loras` array of GET /api/v1/models (SDXL only, subscription required)
`source_image_id`	string	No	-	img2img: the id of one of YOUR images on BetterWaifu, from generate polling or GET /api/v1/images (SDXL only, subscription required)
`strength`	number	No	`0.75`	img2img denoise strength (0.05-1); lower stays closer to the source
`i2i_terms_accepted`	boolean	With `source_image_id`	-	Must be `true` for img2img requests

LoRAs

Pass loras to apply up to 4 LoRAs on top of an SDXL checkpoint. Only the LoRAs listed in the loras array of Models are hosted on the workers — any other id returns a 400. strength per entry ranges 0-2 and defaults to 1.

{ "loras": [{ "model_version_id": 1506035, "strength": 0.8 }] }

Image-to-image

Pass source_image_id (with i2i_terms_accepted: true) to regenerate from one of your existing BetterWaifu images — the endpoint takes no uploads, only ids of images already in your account. Find ids in Images or in any generate poll result. The saved result records its source image for provenance.

Available Samplers

euler_a (recommended)
euler
dpmpp_2m_karras
dpmpp_2m_sde_karras
dpmpp_2m
dpmpp_sde
dpmpp_sde_karras
ddim
ddpm
heun
lms
lms_karras
dpm2
dpm2_a
unipc
pndm
deis
dpm_sde_karras

Example Request

curl -X POST https://betterwaifu.com/api/v1/generate \
  -H "Authorization: Bearer bw_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "1girl, solo, long hair, blue eyes, white dress, standing in a flower field, masterpiece, best quality",
    "negative_prompt": "lowres, bad anatomy, bad hands, text, error, missing fingers",
    "model_version_id": 814910,
    "width": 832,
    "height": 1216,
    "batch_size": 1,
    "steps": 30,
    "cfg_scale": 7,
    "sampler": "euler_a"
  }'

Response

Success Response (201 Created)

{
  "id": "job_abc123def",
  "status": "queued",
  "model_version_id": 814910,
  "model_name": "tPonynai3",
  "credits_charged": 1,
  "seed": 1234567890,
  "created_at": "2026-03-30T19:00:00.000Z",
  "poll_url": "https://betterwaifu.com/api/v1/generate/job_abc123def"
}

Response Fields

Field	Type	Description
`id`	string	Job ID for polling
`status`	string	Initial status (`"queued"`)
`model_version_id`	number	The model version used
`model_name`	string	Human-readable model name
`credits_charged`	number	Credits deducted for this generation
`seed`	number	The seed used (useful for reproducibility)
`created_at`	string	ISO 8601 timestamp
`poll_url`	string	Full URL to poll for results

Error Responses

400 Bad Request

{
  "error": "prompt is required and must be a string"
}

{
  "error": "Your prompt was flagged by moderation. Please revise and try again."
}

{
  "error": "model_version_id is required. Use GET /api/v1/models to list available models."
}

{
  "error": "LoRA 999 is not available. Use the loras array of GET /api/v1/models."
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

402 Payment Required

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

403 Forbidden

{
  "error": "Model version 123456 is not available for generation"
}

{
  "error": "img2img requires an active subscription"
}

{
  "error": "img2img requires i2i_terms_accepted: true — you confirm the source is your own BetterWaifu image and its use follows the content policy."
}

404 Not Found

{
  "error": "Model version 123456 not found"
}

{
  "error": "Source image abc123 not found in your images"
}

429 Too Many Requests

{
  "error": "You already have an active generation. Please wait for it to complete."
}

Notes

Credits are charged immediately when the job is submitted
If a seed is not provided, a random seed is generated server-side
Prompts are subject to content moderation
Only one generation can be active at a time per user
Use the poll_url or id to check on the generation status