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

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."
}

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"
}

404 Not Found

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

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