Image Generation API

ImageGeneration(; prompt, model="gpt-image-1.5", kwargs...)

Configuration struct for an OpenAI Image Generation API request.

Key Fields

• model::String: Model to use (default: "gpt-image-1.5")
• prompt::String: A text description of the desired image
• n::Union{Int,Nothing}: Number of images to generate (1–10)
• size::Union{String,Nothing}: Size ("1024x1024", "1536x1024", "1024x1536", "auto")
• quality::Union{String,Nothing}: Quality level ("low", "medium", "high", "auto")
• background::Union{String,Nothing}: Background ("transparent", "opaque", "auto")
• output_format::Union{String,Nothing}: File format ("png", "webp", "jpeg")
• output_compression::Union{Int,Nothing}: Compression (0–100, for "webp" and "jpeg")
• user::Union{String,Nothing}: End-user identifier

Examples

# Simple prompt
ImageGeneration(prompt="A watercolor painting of a mountain sunset")

# With all options
ImageGeneration(
    prompt="A minimalist logo for a Julia package",
    size="1024x1024",
    quality="high",
    background="transparent",
    output_format="png"
)

ImageObject

A single generated image from the API response.

Fields

• b64_json::Union{String,Nothing}: Base64-encoded image data
• revised_prompt::Union{String,Nothing}: The prompt as revised by the model

ImageResponse

Parsed response from the Image Generation API.

Accessors

• image_data(r) — extract base64-encoded image data
• r.created, r.data, r.usage — basic fields
• r.raw — the complete raw JSON dict

Fields

• created::Int64: Timestamp when the response was created
• data::Vector{ImageObject}: Generated images
• usage::Union{Dict{String,Any},Nothing}: Token usage information
• raw::Dict{String,Any}: Complete raw JSON response

ImageSuccess <: LLMRequestResponse

Successful image generation. Access the parsed response via .response.

Examples

result = generate_image("A cute robot")
if result isa ImageSuccess
    imgs = image_data(result)   # Vector{String} of base64 images
    save_image(imgs[1], "robot.png")
end

ImageFailure <: LLMRequestResponse

HTTP-level failure from the Image Generation API. Contains the response body and status code.

ImageCallError <: LLMRequestResponse

Exception-level error during an Image Generation API call (network, parsing, etc.).

generate_image(ig::ImageGeneration; retries=0)

Send a request to the OpenAI Image Generation API.

Returns ImageSuccess, ImageFailure, or ImageCallError.

Examples

ig = ImageGeneration(prompt="A cute robot learning Julia", quality="high")
result = generate_image(ig)
if result isa ImageSuccess
    println("Generated $(length(result.response.data)) image(s)")
    save_image(image_data(result)[1], "robot.png")
end

generate_image(prompt::String; kwargs...)

Convenience method: create an ImageGeneration from a prompt + keyword arguments and send it.

Examples

# Simple generation
result = generate_image("A watercolor painting of a Julia butterfly")

# With options
result = generate_image(
    "A minimalist logo",
    size="1024x1024",
    quality="high",
    background="transparent"
)

# Save to file
if result isa ImageSuccess
    save_image(image_data(result)[1], "logo.png")
end

image_data(r::ImageResponse)::Vector{String}
image_data(r::ImageSuccess)::Vector{String}

Extract base64-encoded image data from a response. Returns a vector of base64 strings, one per generated image.

Examples

result = generate_image("A sunset over mountains")
imgs = image_data(result)       # Vector{String}
length(imgs)                     # number of images generated

save_image(img_b64::String, filepath::String)

Decode a base64-encoded image and save it to a file.

Examples

result = generate_image("A watercolor landscape")
if result isa ImageSuccess
    save_image(image_data(result)[1], "landscape.png")
end