Image Generations

Generate high-quality images from text prompts using various AI models.

Image generation allows you to create unique visual content directly from textual descriptions (prompts). This capability can be used for creative applications, content creation, design, and more.

How Image Generation Works

You provide a text prompt describing the image you want to create, and the NeosantaraAI API utilizes advanced generative AI models to produce the corresponding image(s). You can specify parameters like the number of images, their size, and the format of the output.

The NeosantaraAI API provides an /v1/images/generations endpoint for this purpose.

Usage

To generate images, send a POST request to the /v1/images/generations endpoint with your text prompt and desired parameters.

Endpoint

POST /v1/images/generations

Request Body

{
  "prompt": "A futuristic city skyline at sunset with flying cars and neon lights, highly detailed, cyberpunk style.",
  "model": "neosantara-gen-2045",
  "n": 1,
  "size": "1024x1024",
  "steps": 50,
  "response_format": "url"
}

Parameters

• prompt (string, required): The text description of the image(s) to generate.
• model (string, optional, default: "neosantara-gen-2045"): The ID of the image generation model to use.
• n (integer, optional, default: 1): The number of images to generate. Must be between 1 and 4.
• size (string, optional, default: "1024x1024"): The size of the generated images. Supported sizes depend on the model but commonly include "512x512", "1024x1024".
• steps (integer, optional, default: 1): The number of diffusion steps for image generation. Higher values generally lead to better quality but take longer.
• response_format (string, optional, default: "url"): The format in which the generated images are returned.
  • "url": Returns a temporary URL to the generated image. These URLs are typically valid for a short period (e.g., 5 minutes).
  • "b64_json": Returns the image data directly as a base64-encoded JSON string.

For b64_json output, may encountered an error. We will fix that later

Supported Image Generation Models

The NeosantaraAI API supports the following image generation models:

• neosantara-gen-2045: Our primary image generation model. Recommended for quality and speed.

Example Response ("response_format": "url")

{
  "id": "img-abcdef1234567890abcdef123456",
  "object": "image",
  "created": 1701234567,
  "model": "neosantara-gen-2045",
  "data": [
    {
      "url": "https://api.neosantara.xyz/share/generated/a1b2c3d4e5f67890a1b2c3d4e5f67890",
      "b64_json": null
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 0,
    "total_tokens": 100
  },
  "_metadata": {
    "creator": "neosantara.xyz",
    "status": true,
    "model_used": "neosantara-gen-2045",
    "tier": "Free",
    "image_count": 1,
    "image_size": "1024x1024",
    "prompt_length": 65,
    "steps": 50,
    "equivalent_tokens_used": 100,
    "response_format": "url",
    "processing_time": 1234,
    "timestamp": "2025-07-28 04:10:00"
  }
}

Example Response ("response_format": "b64_json")

{
  "id": "img-abcdef1234567890abcdef123456",
  "object": "image",
  "created": 1701234567,
  "model": "neosantara-gen-2045",
  "data": [
    {
      "url": null,
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 0,
    "total_tokens": 100
  },
  "_metadata": {
    "creator": "neosantara.xyz",
    "status": true,
    "model_used": "neosantara-gen-2045",
    "tier": "Free",
    "image_count": 1,
    "image_size": "1024x1024",
    "prompt_length": 65,
    "steps": 50,
    "equivalent_tokens_used": 100,
    "response_format": "b64_json",
    "processing_time": 1234,
    "timestamp": "2025-07-28 04:10:00"
  }
}

Python and JavaScript Examples (with OpenAI SDK)

You can generate images using the OpenAI SDK by configuring its base_url to point to the NeosantaraAI API.

Py

from openai import OpenAI
import base64 # Needed if you want to decode and save/display base64

client = OpenAI(
    api_key="NAI_API_KEY",
    base_url="https://api.neosantara.xyz/v1"
)

def generate_image(prompt: str, model: str = "neosantara-gen-2045", num_images: int = 1, size: str = "1024x1024", response_format: str = "url"):
    """
    Generates images from a text prompt using the Neosantara AI API.
    """
    print(f"Generating image(s) for prompt: '{prompt}' with model: {model}")

    try:
        response = client.images.generate(
            model=model,
            prompt=prompt,
            n=num_images,
            size=size,
            response_format=response_format # 'url' or 'b64_json'
        )

        if response_format == "url":
            image_urls = [item.url for item in response.data]
            print("\nGenerated Image URLs:")
            for url in image_urls:
                print(url)
            return image_urls
        elif response_format == "b64_json":
            base64_images = [item.b64_json for item in response.data]
            print(f"\nGenerated {len(base64_images)} base64-encoded images.")
            # Example: To save the first image (requires 'base64' import)
            # with open("generated_image.png", "wb") as f:
            #     f.write(base64.b64decode(base64_images[0]))
            return base64_images
        else:
            print("Unsupported response format.")
            return None

    except Exception as e:
        print(f"\nAn error occurred during image generation: {e}")
        return None

if __name__ == "__main__":
    # Example 1: Generate image and get URL
    image_prompt_url = "A serene Indonesian rice paddy field at sunrise, with a traditional farmer working, cinematic lighting."
    generated_urls = generate_image(image_prompt_url, num_images=1, size="1024x1024", response_format="url")

    # Example 2: Generate image and get base64 data (useful for direct embedding)
    # image_prompt_b64 = "A majestic Komodo dragon basking in the sun on a rocky beach, realistic, high detail."
    # generated_b64_data = generate_image(image_prompt_b64, num_images=1, size="512x512", response_format="b64_json")
    # if generated_b64_data:
    #     print("\nFirst base64 image data (truncated):")
    #     print(generated_b64_data[0][:50], "...")