hot.dev/xai / ::xai::images

Values

DEFAULT_MODEL

DEFAULT_MODEL: Str "grok-imagine-image"

GROK_2_IMAGE

GROK_2_IMAGE: Str "grok-2-image-1212"

GROK_IMAGINE_IMAGE

GROK_IMAGINE_IMAGE: Str "grok-imagine-image"

SIZE_1024

SIZE_1024: Str "1024x1024"

SIZE_256

SIZE_256: Str "256x256"

SIZE_512

SIZE_512: Str "512x512"

Functions

create-image

fn (prompt: Str): Str | ::xai::api/HttpError
fn (prompt: Str, size: Str): Str | ::xai::api/HttpError

Simple image generation - returns the URL of the generated image.

Optionally pass a size string (e.g. "1024x1024") as a second argument.

Example

url create-image("A sunset over mountains")
// => "https://..."

// With custom size
url create-image("A sunset over mountains", "512x512")

detect-format

fn (path: Str): Str?

Detect image format from file path extension. Returns the MIME minor type (e.g. "png") or null.

generate

fn (request: CreateImageRequest): CreateImageResponse | ::xai::api/HttpError

Generate images from a text prompt.

Returns the raw API response with either URLs or base64 data.

Example - URL response (default)

response generate(CreateImageRequest({
    prompt: "A futuristic city at sunset",
    model: "grok-imagine-image"
}))

image-url response.data[0].url

Example - Base64 response

response generate(CreateImageRequest({
    prompt: "A cat wearing a spacesuit",
    model: "grok-imagine-image",
    response_format: "b64_json"
}))

base64-data response.data[0].b64_json

generate-batch-to-files

fn (path-template: Str, prompt: Str, count: Int): ::ai::media/AIMediaBatch

Generate multiple images and save them to files.

Returns an AIMediaBatch with all generated AIMedia.Image items. The path should include a {n} placeholder that will be replaced with the image index (0-based).

Example

batch generate-batch-to-files("uploads/image-{n}.png", "A beautiful landscape", 3)
// Generates: uploads/image-0.png, uploads/image-1.png, uploads/image-2.png

batch.succeeded // => 3
batch.failed // => 0

paths map(batch.items, %.media.file.path)
// => ["uploads/image-0.png", "uploads/image-1.png", "uploads/image-2.png"]

generate-to-file

fn (path: Str, prompt: Str): ::ai::media/AIMedia | ::xai::api/HttpError
fn (path: Str, request: CreateImageRequest): ::ai::media/AIMedia | ::xai::api/HttpError

Generate an image and save it to a file.

Returns an AIMedia.Image with file metadata and AI generation details. The image is requested in base64 format and decoded to bytes for file writing.

Example

result generate-to-file("uploads/city.png", "A futuristic city at sunset")

match result {
    AIMedia.Image => {
        result.media.file.path // => "uploads/city.png"
        result.media.file.size // => 123456
        result.prompt // => "A futuristic city at sunset"
        result.revised_prompt // => "A detailed futuristic city..."
    }

    HttpError => { fail("Image generation failed") }
}

With options

result generate-to-file("output/cat.png", CreateImageRequest({
    prompt: "A cat wearing a spacesuit",
    quality: "hd",
    style: "vivid"
}))

parse-size

fn (size: Str?): Map

Parse size string like "1024x1024" into a Map with width and height keys.

Types

ApiImageData

ApiImageData type {
    url: Str?,
    b64_json: Str?,
    revised_prompt: Str?
}

CreateImageRequest

CreateImageRequest type {
    prompt: Str,
    model: Str?,
    n: Int?,
    quality: Quality?,
    response_format: ResponseFormat?,
    size: Str?,
    style: Style?,
    user: Str?
}

CreateImageResponse

CreateImageResponse type {
    created: Int,
    data: Vec
}

Quality

Quality type "standard" | "hd"

ResponseFormat

ResponseFormat type "url" | "b64_json"

Style

Style type "vivid" | "natural"