Skip to main content

Image Generation

This document provides the technical specifications for the image generation endpoint. By following this guide, you will be able to integrate AI-powered image creation into your applications by structuring requests, specifying models and parameters, and handling the resulting image data.

The AIGNE Hub API allows you to generate new images from a text prompt or edit existing images. For details on other AI functionalities, see the Chat Completions and Embeddings documentation.

Create Image

Generates an image based on a textual description (prompt). You can also provide an existing image to be edited.

Endpoint

sh
POST /api/images/generations

This endpoint creates a new image or edits an existing one, returning the image data in the specified format.

Request Body

  • prompt string (required) — A detailed text description of the desired image. The maximum length depends on the model, but shorter, precise prompts often yield better results.
  • model string (default: dall-e-2) — The model ID to use for image generation. If not specified, the system defaults to dall-e-2. Other models like dall-e-3 or Google's gemini models may be available depending on provider configurations.
  • image string or array — The source image or images for editing. This can be a URL or a Base64 encoded string. Currently, this parameter is utilized by the gpt-image-1 model for image editing tasks.
  • n integer (default: 1) — The number of images to generate. Must be an integer between 1 and 10.
  • size string (default: 1024x1024) — The desired dimensions of the generated image. Supported sizes depend on the selected model. Common values include 256x256, 512x512, and 1024x1024 for DALL·E 2, and 1024x1024, 1792x1024, or 1024x1792 for DALL·E 3.
  • response_format string (default: url) — The format in which the generated images are returned. Must be one of url or b64_json. A url will be accessible for one hour, while b64_json provides the image data encoded in Base64.
  • quality string (default: standard) — The quality of the generated image. Only supported by dall-e-3. Can be standard for faster generation or hd for enhanced detail and higher quality, which may have increased cost.
  • style string (default: vivid) — The artistic style of the generated image. Only supported by dall-e-3. Can be vivid for hyper-realistic and dramatic results or natural for a more photorealistic and less processed look.

Response Body

The API returns an object containing the creation timestamp and an array of generated image data.

  • created integer — A UNIX timestamp indicating when the image generation was initiated.
  • data array — An array of objects, where each object contains one generated image. The structure of the objects inside the array depends on the response_format parameter.
    • object object — Contains either a url or b64_json field with the image data.
      • url string — The URL where the generated image can be accessed. This URL is temporary and will expire.
      • b64_json string — The Base64-encoded JSON string of the generated image.

Examples

Basic Image Generation

This example demonstrates a standard request to generate a single image using the default dall-e-2 model.

Request

bash
curl --location 'https://your-aigne-hub-instance.com/api/images/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "prompt": "A photorealistic image of a cat programming on a laptop",
    "n": 1,
    "size": "1024x1024"
}'

The server returns the URL for the generated image.

Response

json
{
  "created": 1678886400,
  "data": [
    {
      "url": "https://example.com/generated-images/image-xyz.png"
    }
  ]
}

Generating with DALL·E 3 and Base64 Response

This example uses the dall-e-3 model to create a high-quality, vivid image and returns the result as a Base64 encoded string.

Request

bash
curl --location 'https://your-aigne-hub-instance.com/api/images/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": "dall-e-3",
    "prompt": "An oil painting of a futuristic city skyline at sunset, with flying cars",
    "n": 1,
    "size": "1792x1024",
    "quality": "hd",
    "style": "vivid",
    "response_format": "b64_json"
}'

The response contains the Base64 data, which can be directly decoded and saved as an image file.

Response

json
{
  "created": 1678886400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAB...rest_of_base64_string"
    }
  ]
}

Summary

You now have the necessary information to use the image generation endpoint. This includes understanding the request parameters for creating and editing images, as well as handling the different response formats.

For further reading on related API functionalities, please refer to the following documents:

Chat Completions API

Learn how to build conversational experiences with our chat models.

Embeddings API

Discover how to create numerical representations of text for machine learning tasks.