Name: Ideogram v3 – Photorealistic Images | $0.1/call | API.market
Brand: magicapi
SKU: api-magicapi-ideogram-quality-v3-realistic-text-to-image-generator-ai
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Photorealistic Text-to-Image Generator API (Ideogram v3)

## Overview
The Photorealistic Text-to-Image Generator (Ideogram v3) is a high-fidelity API for converting text prompts into stunning, ultra-realistic images. Powered by Ideogram v3, this service produces consistent and creative image designs within seconds. Ideal for developers who want to integrate advanced text-to-image generation into their applications.

![An example input image used for inpainting tasks](https://example.com/image.jpg)

## Features
- Generates ultra-realistic images from text prompts
- Supports custom aspect ratios, resolutions, and style customization
- Inpainting support to seamlessly modify parts of an existing image
- Ability to provide reference style images to guide the output’s aesthetics
- Fine control over random seed for reproducibility

## Use Cases
1. E-commerce Product Photography: Automatically generate or enhance product images with realistic backgrounds or scenes.  
2. Interior Design Mockups: Visualize different interior design concepts by simply changing text prompts and styling options.  
3. Marketing Campaigns: Create eye-catching visuals for promotional materials that require a specific style or theme.  
4. Social Media Content Creation: Craft share-worthy, on-brand images at scale for social platforms.  
5. Concept Art for Entertainment: Rapidly visualize character or scene ideas for film, TV, and gaming projects.

## Visual Examples
Below are a few examples illustrating how inputs and outputs may look. These examples demonstrate the variety of ways you can use text prompts or images as input.

### Inpainting Input
![Mask file used to preserve white pixels and inpaint black pixels](https://example.com/image.jpg)

### Style Reference Image
![A style reference image used to guide the generated style](https://example.com/image.jpg)

### Output for a Succeeded Prediction
![An example final output image generated by the AI](https://blog.api.market/wp-content/uploads/2026/04/Ideogram-quality-api-market.png)

## Pricing
- 1 API unit equals 1 image processed.  
- GET requests to check prediction status are free and do not count toward API unit usage.  
- Different pricing tiers are available based on usage volume. Please contact API.market for more details.

## API Documentation

### Base URL
All requests should be made to:  
```
https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai
```

### Authentication
Authenticate by including your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API uses asynchronous processing for creating image predictions. The typical flow:

1. Make a POST request to create a prediction.  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint with the ID to check the status.  
4. Continue polling until the prediction completes.

Allow for up to 10 minutes of processing time (depending on complexity). If “status” is “failed” or you hit your timeout, handle the error accordingly.

### Endpoints

#### POST /api/v1/magicapi/realistic-text-to-image-generator-ai/predictions
Creates a new prediction using your text prompt and optional parameters (e.g., aspect ratio, style type, images).  

Request Body (JSON):
```json
{
  "version": "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
  "input": {
    "prompt": "A stunning portrait of a young woman in cinematic style",
    "resolution": "None",
    "aspect_ratio": "3:2",
    "style_type": "None",
    "magic_prompt_option": "Off"
  }
}
```

Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
    "input": {
      "prompt": "The text \"V3 Quality\" in the center middle. A color film-inspired portrait of a young woman...",
      "resolution": "None",
      "style_type": "None",
      "aspect_ratio": "3:2",
      "magic_prompt_option": "Off"
    }
  }'
```

Successful Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
  "status": "starting",
  "created_at": "2025-06-22T07:04:25.387Z"
}
```

#### GET /api/v1/magicapi/realistic-text-to-image-generator-ai/predictions/{id}
Retrieves the status of a prediction by its ID.  

Example cURL:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Successful Response (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/04/Ideogram-quality-api-market.png",
  "error": null,
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

## Status Codes
- 200 OK: Request successful.  
- 201 Created: Resource successfully created.  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key but insufficient permissions.  
- 404 Not Found: Resource not found.  
- 429 Too Many Requests: Rate limit exceeded.  
- 500 Internal Server Error: Server-side error.  
- 503 Service Unavailable: Service temporarily unavailable.

## Rate Limits
Various rate limits may apply based on your plan; please consult your plan details or contact us for more information. If you exceed your plan’s limit, you will receive a 429 (Too Many Requests) error.

## Error Handling
When an error occurs, the API returns an appropriate HTTP status code along with a JSON object describing the issue. Handle errors and retries as necessary:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```

Frequently encountered errors include invalid input, missing parameters, or unauthorized requests. Retries for transient errors (like timeouts or 5xx responses) should implement exponential backoff or a reasonable delay.

## Implementation Guide

Below are example code snippets demonstrating how to properly integrate this API in your application.

### Example Code

#### JavaScript (Node.js) Example
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results until finished or time out
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 10 minutes
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      // Return output image URL
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python Example
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
            "input": input_data
        }
    )

    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 10 minutes
    POLL_INTERVAL = 1  # 1 second

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers=headers
        )

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()
        status = prediction["status"]

        if status == "succeeded":
            return prediction["output"]
        elif status == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7a0ab9aed1a1a37b9857e3c4e684e499b9200270ba717449e69fc10940a2831c",
    "input": {
      "prompt": "Generate a photorealistic scenic landscape"
    }
  }'

# The response will include a prediction ID (e.g. "abcd1234").
# Step 2: Poll for Results
curl -X GET "https://prod.api.market/api/v1/magicapi/realistic-text-to-image-generator-ai/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
# Keep polling until the "status" field is "succeeded" or "failed".
```

### Performance Optimization
- Batch requests when possible to reduce overhead.  
- Use appropriate prompts and resolution settings to minimize processing time.  
- Consider caching results if the same prompt is repeatedly requested.

## FAQ
1. **How long does each prediction take?**  
   Typically, predictions complete within seconds, but more complex prompts or larger resolutions can take longer.

2. **What if I need higher resolution images than provided?**  
   You can experiment with the “resolution” parameter or re-scale the generated image afterward using another API or your own pipelines.

3. **Can I use my own image for partial edits or transformations?**  
   Yes, provide an “image” and a matching “mask” to inpaint specific regions.

4. **Do I have to poll the status endpoint constantly?**  
   A 1-second interval is recommended with a total 600-second timeout.

5. **How do I handle errors or failures?**  
   Check the error field in the response and handle it accordingly (e.g., retry with adjusted parameters).

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Generate ultra-realistic images from text prompts in seconds. Supports custom aspect ratios and consistent styles. Try it free on API.market.

Ideogram v3 – Photorealistic Images | $0.1/call | API.market