Generate images¶

Topics: clients, generation, images, requests

Use AIHordeAPISimpleClient when the caller can wait synchronously and wants the SDK to own polling and cleanup. You need a currently available model name; registered users should pass their API key instead of ANON_API_KEY.

Submit a bounded request¶

def image_request(api_key: str = ANON_API_KEY) -> ImageGenerateAsyncRequest:
    """Build one safe image request."""
    return ImageGenerateAsyncRequest(
        apikey=api_key,
        prompt="A lighthouse above a calm sea at dawn",
        models=["AlbedoBase XL (SDXL)"],
        params=ImageGenerationInputPayload(width=512, height=512, steps=20, n=1),
        nsfw=False,
        censor_nsfw=True,
    )


def generate_image(api_key: str = ANON_API_KEY) -> bytes:
    """Generate the first result and return its decoded pixel bytes."""
    client = AIHordeAPISimpleClient()
    status, _request_id = client.image_generate_request(image_request(api_key))
    if not status.generations:
        raise RuntimeError("The request completed without an image")
    image = client.download_image_from_generation(status.generations[0])
    return image.tobytes()

Pass timeout=300 to image_generate_request when your application has a five-minute upper bound. The returned status may contain completed images even when the timeout expires, so inspect status.generations before treating the request as empty.

Verify success by decoding or saving every returned image. The client raises AIHordeRequestError for an API error and AIHordeGenerationTimedOutError when its timeout policy cannot produce a usable result; see the client/error matrix.

The simple client performs best-effort cancellation for unfinished follow-up requests. If your application needs to own that lifecycle, use the manual-request procedure.