Generation Status

Poll the status of a generation request. When the status is succeeded, the response includes the generated image URLs.

Endpoint

GET /api/v1/generate/{id}

Path Parameters

Parameter	Type	Description
`id`	string	The job ID returned from POST /api/v1/generate

Authentication

Requires a valid API key in the Authorization header.

Authorization: Bearer bw_your_api_key_here

Request

No request body required.

Example Request

curl https://betterwaifu.com/api/v1/generate/job_abc123def \
  -H "Authorization: Bearer bw_your_api_key_here"

Response

Queued (200)

The job is waiting in the queue.

{
  "id": "job_abc123def",
  "status": "queued",
  "queue_position": 3
}

Processing (200)

The job is currently being processed.

{
  "id": "job_abc123def",
  "status": "processing"
}

Succeeded (200)

The generation completed successfully.

{
  "id": "job_abc123def",
  "status": "succeeded",
  "output": {
    "images": [
      {
        "url": "https://images.betterwaifu.com/abc123/xyz789.webp",
        "id": "xK9mP2nQ4vR7tY1w"
      }
    ],
    "seed": 1234567890
  }
}

Failed (200)

The generation failed.

{
  "id": "job_abc123def",
  "status": "failed",
  "error": "Generation failed due to an internal error"
}

Response Fields

Field	Type	Description
`id`	string	The job ID
`status`	string	One of: `queued`, `processing`, `succeeded`, `failed`
`queue_position`	number	Position in queue (only when status is `queued`)
`output`	object	Generation output (only when status is `succeeded`)
`output.images`	array	Array of generated images
`output.images[].url`	string	Direct URL to the generated image
`output.images[].id`	string	Image slug/ID for reference
`output.seed`	number	The seed used for generation
`error`	string	Error message (only when status is `failed`)

Error Responses

400 Bad Request

{
  "error": "Generation ID is required"
}

401 Unauthorized

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

404 Not Found

{
  "error": "Generation not found"
}

Polling Strategy

We recommend polling with the following strategy:

Start polling immediately after receiving the job ID
Poll every 2-3 seconds
Stop polling when status is succeeded or failed
Implement a timeout (e.g., 5 minutes) to handle edge cases

Example Polling Code (JavaScript)

async function waitForGeneration(apiKey, jobId, maxAttempts = 120) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://betterwaifu.com/api/v1/generate/${jobId}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
        },
      }
    );
    
    const result = await response.json();
    
    if (result.status === 'succeeded') {
      return result.output;
    }
    
    if (result.status === 'failed') {
      throw new Error(result.error || 'Generation failed');
    }
    
    // Wait 2.5 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 2500));
  }
  
  throw new Error('Generation timed out');
}

Notes

Generated images are automatically saved to your BetterWaifu account
Image URLs are permanent CDN links
The id in the images array is the image slug, which can be used to view the image on the website at https://betterwaifu.com/image/{id}
Polling is idempotent — you can poll as many times as needed without side effects