Skip to content

Image Generation API

This documentation provides an overview of our Image Generation API within AI Refinery. The API enables you to generate images from text prompts using machine learning models (e.g., black-forest-labs/FLUX.1-schnell). You can utilize this API through our SDK using either the AIRefinery or AsyncAIRefinery clients.

Asynchronous Image Generation

The AsyncAIRefinery generates an image asynchronously by sending a POST request to the endpoint.

AsyncAIRefinery.images.generate()

Parameters:
  • prompt (str): The text prompt guiding image generation.
  • model (str): The model name (e.g., black-forest-labs/FLUX.1-schnell).
  • timeout (float | None): Max time (in seconds) to wait for a response. Defaults to 60 seconds if not provided.
  • extra_headers (dict[str, str] | None): Request-specific headers that override any default headers.
  • extra_body (object | None): Additional data to include in the request body, if needed.
  • **kwargs: Additional generation parameters (e.g., "n", "size", "user").
Returns:
  • ImagesResponse: A Pydantic model containing generated image URLs and metadata.
ImagesResponse Object

Represents the full response returned by the Images “generate” endpoint. It contains the following atrributes:

  • created (int): The Unix timestamp of image creation.
  • data (List[Image]): The list of generated images.
  • usage (Optional[Usage]): Token usage information (if available).
Image Object

Represents one generated image and its metadata. Its attributes are:

  • b64_json (Optional[str]): Base64-encoded image data.
  • revised_prompt (Optional[str]): The possibly modified prompt.
  • url (Optional[str]): URL of the generated image.
Usage Object

Holds token-usage statistics for an image request. It has the following attributes:

  • input_tokens (int): Number of tokens in the prompt.
  • input_tokens_details (Dict[str, int]): A breakdown of input token usage.
  • output_tokens (int): Number of tokens in the generated image.
  • total_tokens (int): Total tokens used.
Example Usage
import os  
import asyncio  
from air import AsyncAIRefinery  
from air import login  

# Authenticate using account and API key retrieved from environment variables  
auth = login(  
    account=str(os.getenv("ACCOUNT")),  
    api_key=str(os.getenv("API_KEY")),  
)  

# Get base URL for AI Refinery service from environment variable 
base_url = os.getenv("AIREFINERY_ADDRESS", "")  

async def generate_image_async():  
    # Initialize the asynchronous client for AI Refinery service with authentication details  
    client = AsyncAIRefinery(**auth.openai(base_url=base_url))  

    # Use the images sub-client to asynchronously generate an image based on the given prompt and model  
    response = await client.images.generate(  
        prompt="A painting of a futuristic cityscape in watercolor style",  # Description of the desired image  
        model="black-forest-labs/FLUX.1-schnell"  # Specify the model to use for image generation  
    )  

    # Print the response from the image generation request  
    print("Async image generation response: ", response)  

# Execute the asynchronous image generation function when the script is run  
if __name__ == "__main__":  
    asyncio.run(generate_image_async())

Synchronous Image Generation

AIRefinery.images.generate()

The AIRefinery client generates images in a synchronous manner. This method supports the same parameters and return structure as the asynchronous method (AsyncAIRefinery.images.generate()) described above.

Example Usage
import os  
from air import AIRefinery  
from air import login  

# Authenticate using account and API key retrieved from environment variables  
auth = login(  
    account=str(os.getenv("ACCOUNT")),  
    api_key=str(os.getenv("API_KEY")),  
)  

# Get base URL for AI Refinery service from environment variable
base_url = os.getenv("AIREFINERY_ADDRESS", "")  

def generate_image_sync():  
    # Initialize the synchronous client for AI Refinery service with authentication details  
    client = AIRefinery(**auth.openai(base_url=base_url))  

    # Use the images sub-client to synchronously generate an image based on the given prompt and model  
    response = client.images.generate(  
        prompt="A serene mountain landscape at sunset",  # Description of the desired image  
        model="black-forest-labs/FLUX.1-schnell"  # Specify the model to use for image generation  
    )  

    # Print the response from the image generation request  
    print("Sync image generation response: ", response)  

# Execute the synchronous image generation function when the script is run  
if __name__ == "__main__":  
    generate_image_sync()