Venice AI Image Generation API Resources.

This module provides asynchronous client interfaces for Venice AI's comprehensive Image Generation API, enabling developers to create, manipulate, and enhance images using advanced AI models. The Image API supports a wide range of image generation and editing operations with fine-grained control over output characteristics.

Key Features:

AI Image Generation: Create original images from text prompts
Image Upscaling: Enhance image resolution while preserving quality
Image Editing: Modify existing images based on text instructions
Style Management: Access and apply predefined artistic styles
Format Control: Support for JPEG, PNG, WebP output formats
Advanced Parameters: Fine-tune generation with CFG scale, steps, seeds
Batch Generation: Create multiple image variants efficiently
Asynchronous Operations: Full async/await support for scalable applications

Supported Operations:

Text-to-Image Generation: Transform descriptive text into visual content
Image Enhancement: Upscale images with optional creative enhancement
Image Editing: Modify existing images using natural language instructions
Style Discovery: List available artistic styles for image generation
Format Conversion: Generate images in various formats and resolutions

The image generation process leverages state-of-the-art diffusion models to produce high-quality visual content suitable for diverse applications:

Creative Content: Artwork, illustrations, and concept art
Marketing Materials: Product images, advertisements, and promotional content
Prototyping: Visual mockups and design iterations
Content Enhancement: Image upscaling and quality improvement
Artistic Exploration: Style transfer and creative image manipulation

Example:

.. code-block:: python

import asyncio from venice_ai import VeniceClient

async def generate_artwork(): async with VeniceClient() as client:

Generate an original image from text

response = await client.image.create( model="venice-sd35", prompt="A serene mountain landscape at sunset", width=1024, height=768, style_preset="cinematic" )

Extract and save the generated image

import base64 image_data = base64.b64decode(response.images[0]) with open("mountain_sunset.png", "wb") as f: f.write(image_data)

asyncio.run(generate_artwork())

Performance Considerations:

Image generation time scales with complexity and resolution
Batch generation is more efficient than individual requests
Higher step counts improve quality but increase generation time
Model selection affects both quality and processing speed

Notes:

All operations in this module are asynchronous and require proper async/await handling. The Image class is accessed through the :attr:VeniceClient.image property and provides comprehensive image generation and manipulation capabilities.

ImageJob Objects

class ImageJob()

Manages a single image generation request as an async context manager.

Mirrors :class:venice_ai.resources.music.MusicJob / :class:venice_ai.resources.video.VideoJob for API symmetry — but image generation is synchronous on the server (no queue / poll endpoint), so the work happens inside :meth:wait and there is no server-side state to clean up on exit. The shape matters for parallel rendering:

    async with VeniceClient() as client:
        jobs = [
            await client.image.submit(model=m, prompt=p)
            for p in prompts
        ]
        # Hold all jobs open while rendering in parallel
        async with contextlib.AsyncExitStack() as stack:
            for j in jobs:
                await stack.enter_async_context(j)
            images = await client.gather(
                [j.wait() for j in jobs],
                max_concurrency=4,
            )

For one-off rendering, ``client.image.create(...)`` is still the
shorter path.

ImageJob.wait

async def wait() -> ImageGenerationResponse | bytes

Run the image generation and cache the result.

Subsequent calls return the cached value without re-issuing the request. Raises whatever :meth:Image.create would raise.

ImageJob.download

async def download(path: str | Path) -> Path

Save the rendered image to path and return the resolved Path.

Calls :meth:wait if the result hasn't been fetched yet. The output format is inferred from self._kwargs.get("format") and the API response shape.

Image Objects

class Image(APIResource["VeniceClient"])

Provides access to asynchronous image generation, upscaling, and style listing operations.

This class manages asynchronous image operations using Venice AI's image API. It encapsulates functionality for image generation, upscaling, and style listing through a clean, typed interface that makes asynchronous HTTP requests.

All methods in this class make asynchronous HTTP requests using async/await syntax.

Arguments:

client (venice_ai._client.VeniceClient): The Venice AI client instance used for making API requests.

Image.create

async def create(
    *,
    model: str,
    prompt: str,
    aspect_ratio: str | None = None,
    cfg_scale: float | None = None,
    embed_exif_metadata: bool | None = None,
    enable_web_search: bool | None = None,
    format: Literal["jpeg", "png", "webp"] | None = None,
    height: int | None = None,
    hide_watermark: bool | None = None,
    lora_strength: int | None = None,
    num_images: int | None = None,
    quality: Literal["low", "medium", "high"] | None = None,
    resolution: str | None = None,
    return_binary: bool | None = None,
    safe_mode: bool | None = None,
    seed: int | None = None,
    steps: int | None = None,
    style_preset: str | None = None,
    width: int | None = None,
    timeout: float | aiohttp.ClientTimeout | None = None
) -> ImageGenerationResponse | bytes

Generate an image using Venice AI's image generation API asynchronously.

This method creates a new image based on a text prompt using the specified model, executing the request asynchronously for use in async/await contexts. It provides comprehensive control over the image generation process with multiple parameters to customize the output.

Arguments:

model (str): Model ID for image generation (e.g., "venice-sd35").
prompt (str): Text prompt describing the image to generate.
aspect_ratio (Optional[str]): Optional. Aspect ratio for the output (e.g. "1:1", "16:9"). Supported values vary by model; inspect GET /models for per-model allowed values.
cfg_scale (Optional[float]): Optional. Classifier Free Guidance scale (range: (0, 20]). Higher values adhere more strictly to the prompt.
embed_exif_metadata (Optional[bool]): Optional. If True, embed generation metadata in EXIF data.
enable_web_search (Optional[bool]): Optional. If set, the image model may incorporate recent web-search context. Supported by models with the supportsWebSearch capability.
format (Optional[Literal["jpeg", "png", "webp"]]): Optional. Output image format.
height (Optional[int]): Optional. Height of the generated image in pixels.
hide_watermark (Optional[bool]): Optional. If True, hide Venice AI watermark from the generated image.
lora_strength (Optional[int]): Optional. Strength of LoRA model adaptation (0-100).
num_images (Optional[int]): Optional. Number of images to generate (1-4).
quality (Optional[Literal["low", "medium", "high"]]): Optional. Output quality for quality-aware models (e.g. GPT Image 2). Higher values can increase the request charge. See the model spec's qualities field for supported values per model.
resolution (Optional[str]): Optional. Output resolution: "1K", "2K", or "4K" for supported models with resolution-based pricing.
return_binary (Optional[bool]): Optional. If True, return raw image bytes instead of JSON response with base64 data.
safe_mode (Optional[bool]): Optional. If True, enable content filtering for safer outputs.
seed (Optional[int]): Optional. Random seed for reproducible image generation results.
steps (Optional[int]): Optional. Number of diffusion steps. Higher values generally improve quality but increase generation time.
style_preset (Optional[str]): Optional. Style preset ID from :meth:list_styles to apply to the generated image.
width (Optional[int]): Optional. Width of the generated image in pixels.
timeout (Optional[Union[float, aiohttp.ClientTimeout]]): Optional. Per-request timeout override (seconds or an aiohttp.ClientTimeout). Useful for slow renders such as quality='high' that exceed the client default. Falls back to the client's configured timeout when omitted.

Raises:

venice_ai.exceptions.APIError: If an API error occurs during image generation. Example:

.. code-block:: python

async with VeniceClient() as client:
    response = await client.image.create(
        model="venice-sd35",
        prompt="A serene landscape with mountains and a lake",
        width=1024,
        height=768,
        steps=30
    )
    # Process response.images[0] (base64 string)

Returns:

Response containing generated image data as base64 string, or raw image bytes if return_binary is True.

Image.submit

async def submit(*,
                 model: str,
                 prompt: str,
                 aspect_ratio: str | None = None,
                 cfg_scale: float | None = None,
                 embed_exif_metadata: bool | None = None,
                 enable_web_search: bool | None = None,
                 format: Literal["jpeg", "png", "webp"] | None = None,
                 height: int | None = None,
                 hide_watermark: bool | None = None,
                 lora_strength: int | None = None,
                 num_images: int | None = None,
                 quality: Literal["low", "medium", "high"] | None = None,
                 resolution: str | None = None,
                 return_binary: bool | None = None,
                 safe_mode: bool | None = None,
                 seed: int | None = None,
                 steps: int | None = None,
                 style_preset: str | None = None,
                 width: int | None = None) -> ImageJob

Build an :class:ImageJob for parallel-friendly image generation.

Mirrors the shape of :meth:Music.run / :meth:Video.run so callers can use the same async with await client.image.submit(...) as job: idiom across modalities. Image generation is synchronous on the server (no queue endpoint), so the actual HTTP request fires inside :meth:ImageJob.wait. Use this when you want to render multiple images in parallel via :meth:VeniceClient.gather and need each one's lifecycle bound to a context manager.

For a single one-shot render, :meth:Image.create is shorter.

Accepts the same keyword arguments as :meth:Image.create minus the negative_prompt parameter (removed in v2.0.0).

Returns:

:class:ImageJob ready to use as an async context manager.

Image.upscale

async def upscale(
        *,
        image: str | bytes | BinaryIO | Path,
        enhance: bool | None = None,
        enhanceCreativity: float | None = None,
        enhancePrompt: str | None = None,
        replication: float | None = None,
        scale: float | None = None,
        timeout: float | aiohttp.ClientTimeout | None = None) -> bytes

Upscale an image using Venice AI's image upscaling API asynchronously.

This method allows for increasing the resolution of an image while maintaining or enhancing its quality using Venice AI's upscaling technology, in an asynchronous manner compatible with asyncio applications.

Arguments:

image: Image to upscale. Can be a file path (string or :class:pathlib.Path), raw image bytes, or a file-like object.
enhance (Optional[bool]): Optional. Whether to enhance image quality during upscaling.
enhanceCreativity (Optional[float]): Optional. Creativity level for enhancement (0.0-1.0, where 1.0 is most creative).
enhancePrompt (Optional[str]): Optional. Text to image style to apply during prompt enhancement.
replication (Optional[float]): Optional. Replication factor for matching the original image (0.0-1.0, where 1.0 matches exactly).
scale (Optional[float]): Optional. Scaling factor for upscaling (e.g., 2.0 for 2x upscaling).
timeout (Optional[Union[float, aiohttp.ClientTimeout]]): Optional. Request timeout configuration.

Raises:

ValueError: If image path is invalid or image type is unsupported.
TypeError: If image content type is unsupported.
venice_ai.exceptions.APIError: If an API error occurs during upscaling.

Returns:

Raw bytes of the upscaled image.

Image.list_styles

async def list_styles() -> ImageStylesResponse

List available image style presets asynchronously for use with image generation.

This method retrieves all available style presets that can be used with the style_preset parameter in the :meth:create method to influence the aesthetic and artistic style of generated images. It performs this operation asynchronously.

Raises:

venice_ai.exceptions.APIError: If an API error occurs while retrieving styles.

Returns:

A list of available image style presets with their identifiers.

Image.edit

async def edit(*,
               prompt: str,
               model: str | None = None,
               image: str | bytes | BinaryIO | Path,
               aspect_ratio: str | None = None,
               safe_mode: bool | None = None,
               resolution: str | None = None,
               output_format: Literal["jpeg", "png", "webp"] | None = None,
               quality: Literal["low", "medium", "high"] | None = None,
               timeout: float | aiohttp.ClientTimeout | None = None) -> bytes

Edit an image based on a text prompt asynchronously.

This method modifies an existing image according to text instructions, such as changing colors, removing objects, or altering scenes using Venice AI's image editing capabilities, in an asynchronous manner compatible with asyncio applications.

Binary inputs (file paths, bytes, file-like objects) are base64-encoded and sent in the JSON body. Base64 strings and URLs are forwarded as-is.

Arguments:

prompt (str): Text directions to edit or modify the image. Per-model cap via promptCharacterLimit on GET /models; the endpoint spec ceiling is 32768 characters.
model (Optional[str]): Optional. Edit model to use (e.g., "flux-2-max-edit", "gpt-image-1-5-edit", "nano-banana-pro-edit"). Defaults to the API's server-side default edit model when omitted.
image: The image to edit. Can be:
A file path (string or Path)
Raw image bytes
A file-like object opened in binary mode
A base64-encoded string
An HTTP/HTTPS URL
aspect_ratio (Optional[str]): Optional. Aspect ratio for the output (e.g. "1:1", "16:9"). Omit to use the model's default; supported values vary by model.
safe_mode (Optional[bool]): Optional. When True (the server-side default) the API blurs images classified as adult content. Pass False to disable blurring on adult-capable models.
resolution (Optional[str]): Optional. Resolution tier for the output image. Supported values: "1K", "2K", "4K"; defaults to "1K" server-side when omitted.
output_format (Optional[Literal["jpeg", "png", "webp"]]): Optional. Output format for the edited image. When omitted, the format is inferred from resolution (PNG for 1K edits, JPEG for 2K/4K edits).
timeout (Optional[Union[float, aiohttp.ClientTimeout]]): Optional. Request timeout configuration. Pass a float (seconds) or an :class:aiohttp.ClientTimeout instance. Overrides the client-level default for this call only.

Raises:

ValueError: If the prompt exceeds maximum length or image format is invalid.
TypeError: If image content type is unsupported.
venice_ai.exceptions.VeniceError: If image file is not found or API error occurs. Example:

.. code-block:: python

async with VeniceClient() as client:
    # Edit an image file
    with open('sunset.jpg', 'rb') as f:
        edited = await client.image.edit(
            prompt="Change the sky to a sunrise",
            image=f,
        )

    # Save the result
    with open('sunrise.jpg', 'wb') as f:
        f.write(edited)

    # Pick a specific edit model
    edited = await client.image.edit(
        prompt="Remove the background",
        image="photo.jpg",
        model="flux-2-max-edit",
    )

    # Edit using a URL, with safe_mode disabled
    edited = await client.image.edit(
        prompt="Add a rainbow",
        image="https://example.com/photo.jpg",
        safe_mode=False,
    )

Returns:

The edited image as raw bytes.

Image.background_remove

async def background_remove(*,
                            image: str | bytes | BinaryIO | Path | None = None,
                            image_url: str | None = None) -> bytes

Remove background from an image (POST /image/background-remove).

Remove the background from an image using AI. The image can be provided as a file path, bytes, file-like object, base64 string, or URL. Returns a PNG image with transparent background.

Arguments:

image (Optional[Union[str, bytes, BinaryIO, Path]]): Image as file path, bytes, file-like object, or base64 string.
image_url (Optional[str]): HTTP/HTTPS URL of the image.

Raises:

ValueError: If neither image nor image_url is provided.
venice_ai.exceptions.APIError: If an API error occurs. Example:

.. code-block:: python

async with VeniceClient() as client:
    # Remove background from a file
    result = await client.image.background_remove(
        image="photo.jpg"
    )
    with open("no_bg.png", "wb") as f:
        f.write(result)

    # Remove background from a URL
    result = await client.image.background_remove(
        image_url="https://example.com/photo.jpg"
    )

Returns:

PNG image bytes with transparent background.

Image.multi_edit

async def multi_edit(
        *,
        prompt: str,
        model: str | None = None,
        image: str | bytes | BinaryIO | Path | None = None,
        image_2: str | bytes | BinaryIO | Path | None = None,
        image_3: str | bytes | BinaryIO | Path | None = None,
        safe_mode: bool | None = None,
        resolution: str | None = None,
        aspect_ratio: str | None = None,
        output_format: Literal["jpeg", "png", "webp"] | None = None,
        quality: Literal["low", "medium", "high"] | None = None) -> bytes

Edit an image using up to 3 layered inputs (POST /image/multi-edit).

Composite up to three images with a single prompt. The first image is the base; remaining images are layered on top. Supports both base64 strings and URLs; bytes/file-like/Path inputs are encoded as base64.

Arguments:

prompt (str): Edit instruction describing the desired changes.
model (Optional[str]): Edit model to use (sent as modelId).
image (Optional[Union[str, bytes, BinaryIO, Path]]): Base image (file path, bytes, file-like object, base64, or URL).
image_2 (Optional[Union[str, bytes, BinaryIO, Path]]): Second layer image.
image_3 (Optional[Union[str, bytes, BinaryIO, Path]]): Third layer image.
safe_mode (Optional[bool]): When True (server default) blur adult content. Pass False to disable.
resolution (Optional[str]): Optional. Resolution tier for the output image. Supported values: "1K", "2K", "4K"; defaults to "1K" server-side when omitted.
aspect_ratio (Optional[str]): Optional. Aspect ratio for the output (e.g. "1:1", "16:9"). Omit to infer from the first input image; supported values vary by model.
output_format (Optional[Literal["jpeg", "png", "webp"]]): Optional. Output format for the edited image. When omitted, the format is inferred from resolution (PNG for 1K edits, JPEG for 2K/4K edits).
quality (Optional[Literal["low", "medium", "high"]]): Optional. Output quality for quality-aware models (e.g. GPT Image 2). Higher values can increase the request charge.

Raises:

venice_ai.exceptions.APIError: If an API error occurs. Example:

.. code-block:: python

async with VeniceClient() as client:
    # Multi-edit with file uploads
    result = await client.image.multi_edit(
        prompt="Replace the sky with a sunset",
        image="photo.jpg",
        image_2="sky_overlay.png",
    )
    with open("edited.png", "wb") as f:
        f.write(result)

    # Multi-edit with URLs
    result = await client.image.multi_edit(
        prompt="Blend these images together",
        image="https://example.com/base.jpg",
        image_2="https://example.com/overlay.jpg",
    )

Returns:

Edited image bytes.

Image.simple_generate

async def simple_generate(
        *,
        prompt: str,
        model: str | None = None,
        n: int | None = None,
        size: (Literal[
            "auto",
            "256x256",
            "512x512",
            "1024x1024",
            "1536x1024",
            "1024x1536",
            "1792x1024",
            "1024x1792",
        ]
               | None) = None,
        response_format: Literal["b64_json", "url"] | None = None,
        output_format: Literal["jpeg", "png", "webp"] | None = None,
        quality: Literal["auto", "high", "medium", "low", "hd", "standard"]
    | None = None,
        style: Literal["vivid", "natural"] | None = None,
        background: Literal["transparent", "opaque", "auto"] | None = None,
        moderation: Literal["low", "auto"] | None = None,
        output_compression: int | None = None,
        user: str | None = None) -> SimpleImageGenerationResponse

Generate an image via the OpenAI-compatible POST /images/generations endpoint.

Drop-in replacement for the OpenAI Images API; accepts the OpenAI-compatible parameter set rather than Venice's native fields. For full Venice features (LoRA, CFG, multi-variant) use :meth:create.

Arguments:

prompt: Image description (≤1500 chars per spec).
model: Venice model ID. Defaults to "default" server-side.
n: Number of images. Venice supports n=1 only.
size: Output dimensions, e.g. "1024x1024". "auto" lets the server pick.
response_format: "b64_json" (default) returns base64-encoded data; "url" returns a data URL.
output_format: Image encoding (jpeg/png/webp).
quality: Output quality. Supported by quality-aware models (e.g. GPT Image 2); higher values can increase the request charge. Ignored by models that do not advertise quality support (see the model spec's qualities field).
style: OpenAI-compatibility flag.
background: OpenAI-compatibility flag.
moderation: "auto" enables Venice safe-mode; "low" relaxes it.
output_compression: 0–100; OpenAI-compatibility flag.
user: End-user identifier; OpenAI-compatibility flag.

Returns:

:class:SimpleImageGenerationResponse with created and data (a list of :class:SimpleImageData, each with b64_json or url).

Extract and save the generated image

ImageJob Objects​

ImageJob.wait​

ImageJob.download​

Image Objects​

Image.create​

Image.submit​

Image.upscale​

Image.list_styles​

Image.edit​

Image.background_remove​

Image.multi_edit​

Image.simple_generate​

ImageJob Objects

ImageJob.wait

ImageJob.download

Image Objects

Image.create

Image.submit

Image.upscale

Image.list_styles

Image.edit

Image.background_remove

Image.multi_edit

Image.simple_generate