Run an alchemy operation¶

Topics: alchemy, clients, images, requests

The source image must be a public HTTP(S) URL or a base64 string. Choose one or more values from KNOWN_ALCHEMY_TYPES; each form produces its own state and result.

def caption_image(source_image_url: str, api_key: str = ANON_API_KEY) -> str:
    """Request a caption for an image available at a public URL."""
    request = AlchemyAsyncRequest(
        apikey=api_key,
        source_image=source_image_url,
        forms=[AlchemyAsyncRequestFormItem(name=KNOWN_ALCHEMY_TYPES.caption)],
    )
    status, _request_id = AIHordeAPISimpleClient().alchemy_request(request)
    if not status.forms or not isinstance(status.forms[0].result, AlchemyCaptionResult):
        raise RuntimeError("The request completed without a caption")
    return status.forms[0].result.caption

Call caption_image("https://example.invalid/public-image.webp") with a real public URL. Verify that status.forms contains a caption form in a completed state and that its typed result contains text.

Alchemy jobs cannot be edited after submission. The simple client cleans up an unfinished request; a manual client must send AlchemyDeleteRequest with the returned generation ID. See the alchemy model reference for the other result types.