Name: Ideogram v3 Turbo – AI Image Generation | $0.04/call | API.market
Brand: magicapi
SKU: api-magicapi-ideogram-v3-turbo-ultra-fast-text-to-image-ai-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# ⚡ Ultra-Fast Text-to-Image Generator API (Ideogram v3 Turbo)

## Overview
The Ultra-Fast Text-to-Image Generator API (Ideogram v3 Turbo) enables you to generate highly realistic and creative images from text prompts in just seconds. This model, known for its exceptional speed and cost-efficiency, consistently renders images that exhibit remarkable style and fidelity. Whether you need photo-realistic results or more artistic designs, Ideogram v3 Turbo quickly delivers a variety of stunning images.

## Features
- Lightning-Fast Generation: Get your results in seconds, perfect for time-sensitive applications.  
- Creative Variations: The model excels at producing unique designs and styles.  
- High Realism: From real-life portraits to scenic landscapes, outputs closely mimic professional photography and illustration.  
- Flexible Input Options: Provide text prompts, optional mask images for inpainting, and style reference images.  
- Consistent Results with Seed: Use a seed for reproducible generation across multiple requests.

## Use Cases
1. Product Prototyping for E-Commerce  
   Generate multiple product design variations or mockups quickly, reducing the need for costly photo shoots.  
2. Marketing & Social Media Visuals  
   Instantly create eye-catching promotional images based on specific text prompts for campaigns and social media posts.  
3. Storytelling & Concept Art  
   Writers, game designers, and filmmakers can visualize characters and scenes quickly without hiring a professional artist for every iteration.  
4. Architectural Previsualization  
   Produce quick conceptual renders for interior designs and architectural layouts from simple text prompts.  
5. Personalized Artwork Generation  
   Offer users the ability to transform their ideas into unique, personalized digital artwork.

## Visual Examples

Below are examples illustrating how input and output might look. These examples are taken from the OpenAPI schema:

### Input Example
A simple prompt with an example reference image:  
![Input Reference Image](https://example.com/image.jpg)  
Prompt:  
"The text 'V3 Turbo' in the center middle. A color film-inspired portrait of a young man looking to the side with a shallow depth of field that blurs the surrounding elements, drawing attention to his eye. The fine grain and cast suggest a high ISO film stock, while the wide aperture lens creates a motion blur effect, enhancing the candid and natural documentary style."

### Output Example
Once the generation is complete, the API might return an image like:  
![Output Example Image](https://replicate.delivery/xezq/WHz71UTYXvrTNNeSSZr8ZW9q6W2MwgbcKiTgqumFpBElwIUKA/tmp0s1h52uw.png)

These visuals demonstrate how the API transforms textual descriptions and optional reference images into stunning, high-quality outputs.

## Pricing
• 1 API unit = 1 image processed.  
• Checking prediction status (GET /api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions/{id}) does not consume any credits.  
• Multiple pricing tiers are available based on usage. Contact us to explore the best tier for your project volume.

## API Documentation

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

### Authentication
Use your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API features asynchronous processing. When you create a prediction, the response contains a unique ID. You then poll the GET endpoint with that ID to check if the image generation has finished.  
1. POST to create a prediction (returns an ID).  
2. GET the prediction by ID until the status changes from "starting" or "processing" to "succeeded" (or "failed").  
3. Use a polling interval of 1 second.  
4. Implement a maximum wait timeout of 600 seconds (10 minutes).

### Endpoints

#### 1. Create a Prediction
• Endpoint:  
  POST /api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions  

• Request Body (JSON):
```json
{
  "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
  "input": {
    "prompt": "Your descriptive text prompt here",
    "aspect_ratio": "3:2",
    "resolution": "None",
    "style_type": "None",
    "magic_prompt_option": "Auto"
  }
}
```

• Sample Curl:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
    "input": {
      "prompt": "The text \"V3 Turbo\" in the center middle.",
      "aspect_ratio": "3:2",
      "resolution": "None"
    }
  }'
```

• Example Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
  "status": "starting",
  "created_at": "2025-06-22T07:04:24.785Z"
}
```

#### 2. Get Prediction Status & Result
• Endpoint:  
  GET /api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions/{id}

• Parameters:  
  {id} (path): The prediction ID returned from the create endpoint.

• Sample Curl:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

• Example Response (200 OK, succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/xezq/WHz71UTYXvrTNNeSSZr8ZW9q6W2MwgbcKiTgqumFpBElwIUKA/tmp0s1h52uw.png",
  "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 was successful (e.g., fetched prediction details).  
- 201 Created: Resource successfully created (e.g., a new prediction).  
- 400 Bad Request: Input validation failed or malformed request.  
- 401 Unauthorized: Invalid or missing API key.  
- 403 Forbidden: The API key is valid but does not have permission to access the endpoint.  
- 404 Not Found: The requested resource does not exist (e.g., invalid prediction ID).  
- 429 Too Many Requests: You have hit the rate limit; try again later.  
- 500 Internal Server Error: A server-side error occurred.  
- 503 Service Unavailable: The service is temporarily offline for maintenance or is overloaded.

## Rate Limits
Depending on your subscription plan, certain limits apply to the number of requests you can make per minute/hour/day. If you exceed these limits, you’ll receive a 429 Too Many Requests response. Back off or reduce request frequency when hitting this error.

## Error Handling
If an error occurs, the API returns a JSON response with details:

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

Recommended best practices:
- Check the HTTP status code and the error object for more information.  
- Handle 400 errors by verifying your input parameters.  
- For 401 errors, ensure you’re using a valid and active API key.  
- Implement a retry strategy for 429 errors, waiting before retrying.  
- Use timeouts and re-polling logic for asynchronous operations.

## Implementation Guide

Below are examples of how to integrate with this API, including asynchronous handling:

### JavaScript Example (Node.js)

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator";

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

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

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

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

    // Step 2: Poll for results with a max timeout of 600 seconds
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error in createAndWaitForPrediction:", error);
    throw error;
  }
}

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

  const startTime = Date.now();

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

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

    const predictionStatus = await statusResponse.json();

    if (predictionStatus.status === "succeeded") {
      return predictionStatus.output;
    }

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

    // Wait and then poll again
    await delay(POLL_INTERVAL);
  }

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

// Example usage
(async () => {
  const input = {
    prompt: "A stunning cityscape at sunset in neon colors."
  };
  try {
    const result = await createAndWaitForPrediction(input);
    console.log("Prediction output URL:", result);
  } catch (err) {
    console.error("Error:", err);
  }
})();
```

### Python Example

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator"
MAX_TIMEOUT = 600  # 10 minutes
POLL_INTERVAL = 1  # 1 second

def create_and_wait_for_prediction(input_data):
    # Step 1: Create a prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    payload = {
        "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", json=payload, headers=headers)
    if response.status_code != 201 and response.status_code != 200:
        raise Exception(f"API error: {response.status_code} {response.text}")

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

    # Step 2: Poll for the result
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    start_time = time.time()

    while (time.time() - start_time) < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers={"x-magicapi-key": API_KEY})
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction_status = response.json()

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

        time.sleep(POLL_INTERVAL)

    raise TimeoutError("Prediction timed out after 10 minutes")

# Example usage
if __name__ == "__main__":
    input_data = {
        "prompt": "A futuristic robot painting a canvas in a neon-lit studio."
    }
    try:
        output_url = create_and_wait_for_prediction(input_data)
        print("Generated image URL:", output_url)
    except Exception as e:
        print("Error:", e)
```

### cURL Example

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
    "input": {
      "prompt": "A futuristic robot painting a canvas in a neon-lit studio."
    }
  }'

# Response example:
# {
#   "id": "abcd1234",
#   "version": "f8a8eb2c75d7d86ec58e3b8309cee63acb437fbab2695bc5004acf64d2de61a7",
#   "status": "starting",
#   "created_at": "..."
# }

# Step 2: Poll for results until status is 'succeeded'
curl -X GET "https://prod.api.market/api/v1/magicapi/ultra-fast-text-to-image-ai-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

## Performance Optimization
- Keep prompts concise to reduce processing time.  
- Reuse a seed to maintain consistent image generation across multiple API calls.  
- Use lower-latency network regions if available.  
- Implement caching for previously generated results if you use the same prompt frequently.

## FAQ
1. How long does image generation typically take?  
   – Most predictions complete within a few seconds, though more complex prompts can take longer.  
2. Can I run multiple predictions in parallel?  
   – Yes, but consider rate limits and concurrency restrictions in your plan.  
3. How do I troubleshoot invalid parameter errors?  
   – Check that your JSON payload matches the required schema (particularly the required "prompt" field).  
4. Are there recommended prompt engineering techniques?  
   – Yes! Providing clear and detailed prompts improves output quality.

## 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 realistic and creative AI images from text prompts in seconds. Fast, creative results. From $0.04/call. Try it free on API.market.