Name: Text-to-Image Generator API (GPT-Image 1.5)
Brand: magicapi
SKU: api-magicapi-image-generation-api-openai-gpt-image-1-5
Availability: InStock
Author: API Market

Shashank Agarwal

# 🖼️ Text-to-Image Generator API (GPT-Image 1.5)

## Overview
The Text-to-Image Generator API (GPT-Image 1.5) by OpenAI enables you to generate high-quality images from text prompts, optionally guided by reference images. Leveraging OpenAI's latest advancements in image generation, this API offers enhanced instruction-following capabilities and adherence to prompts, resulting in highly accurate and visually appealing outputs.

## Features
- Generate images from descriptive text prompts
- Optionally use reference images to guide generation
- Control over image quality, aspect ratio, and background transparency
- Supports a variety of output formats (PNG, JPEG, WebP)
- Content moderation and user filtering
- Asynchronous processing for efficient handling of requests

## Use Cases
### Content Creation
Create unique visuals and illustrations for blog posts, social media, and marketing campaigns by simply describing the desired scene or object.

### E-commerce
Generate product images based on text descriptions, enabling a wide variety of product visuals without the need for extensive photoshoots.

### Entertainment
Create visual assets for video games, movies, and virtual experiences. Describe characters, scenes, or objects and bring them to life.

### Education
Develop visual aids and educational content by describing complex concepts or historical scenes, aiding better understanding and engagement.

### Art and Design
Artists and designers can experiment with new styles and concepts by generating images from textual descriptions, exploring creative possibilities.

## Visual Examples

### Example Input

```json
{
  "input": {
    "prompt": "make a scene in chelsea, london in the 1970s, photorealistic, everything in focus, with tons of people, and a red double decker bus with an advertisement for \"ImageGen 1.5 on api.market\" with the subtitle \"Create what you imagine\". Hyper-realistic amateur photography, iPhone snapshot quality",
    "quality": "medium",
    "aspect_ratio": "3:2",
    "output_format": "webp",
    "number_of_images": 1
  }
}
```

### Example Output

![Example output](https://blog.api.market/wp-content/uploads/2026/09/gpt-image-1-5-output-api-market.webp)

This exact request was run through api.market and billed 4 API units ($0.068).
## Pricing
- Pay As You Go (PAYG) pricing - you only pay for what you use
- Price: $0.017 per API unit.
- 1 API unit = 1 output image; a request that returns several images is billed for each one.
- The base rate applies to requests with quality: "low".
- Requests with quality: "medium" count as 3.846 units per image, rounded up to whole units per request (one image bills 4 units).
- Requests with quality: "auto" count as 10.462 units per image, rounded up to whole units per request (one image bills 11 units).
- Requests with quality: "high" count as 10.462 units per image, rounded up to whole units per request (one image bills 11 units).
- A request that does not choose a variant uses the model default and counts as 10.462 units per image (one image bills 11 units).
- Failed or cancelled predictions are not billed
- GET requests to check prediction status (GET /api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions/{id}) are free and don't count toward API unit usage
- No monthly subscription fee

## API Documentation
### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5`

### Authentication
Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Input Parameters
| Parameter        | Type       | Default | Required | Allowed Values                                    | Description                                                                           |
|------------------|------------|---------|----------|--------------------------------------------------|---------------------------------------------------------------------------------------|
| prompt           | string     | N/A     | Yes      | N/A                                              | A text description of the desired image                                               |
| quality          | string     | auto    | No       | low, medium, high, auto                          | The quality of the generated image                                                    |
| user_id          | string     | N/A     | No       | N/A                                              | An optional unique identifier representing your end-user                              |
| background       | string     | auto    | No       | auto, transparent, opaque                        | Set whether the background is transparent, opaque, or choose automatically            |
| moderation       | string     | auto    | No       | auto, low                                        | Content moderation level                                                              |
| aspect_ratio     | string     | 1:1     | No       | 1:1, 3:2, 2:3                                    | The aspect ratio of the generated image                                               |
| input_images     | array      | N/A     | No       | N/A                                              | A list of images to use as input for the generation                                   |
| output_format    | string     | webp    | No       | png, jpeg, webp                                  | Output format                                                                         |
| input_fidelity   | string     | low     | No       | low, high                                        | Control the effort the model will exert to match the style and features of input images|
| openai_api_key   | string     | N/A     | No       | N/A                                              | Your OpenAI API key (optional - uses proxy if not provided)                           |
| number_of_images | integer    | 1       | No       | 1-10                                             | Number of images to generate                                                          |
| output_compression | integer  | 90      | No       | 0-100                                            | Compression level (0-100%)                                                            |

### Asynchronous Processing
**IMPORTANT**: This API uses asynchronous processing for predictions. The typical flow is:

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

Your code should implement:
- A polling interval of 1 second between status checks
- A maximum timeout of 600 seconds (10 minutes)
- Status checking logic that continues while status is "starting" or "processing"
- Result handling when status becomes "succeeded"
- Error handling when status becomes "failed" or "canceled", or timeout is reached

### Endpoints
#### Create a Prediction

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "118f53498ea7319519229b2d5bd0d4a69e3d77eb60d6292d5db38125534dc1ca",
    "input": {
      "prompt": "make a scene in chelsea, london in the 1970s, photorealistic, everything in focus, with tons of people, and a red double decker bus with an advertisement for \"ImageGen 1.5 on api.market\" with the subtitle \"Create what you imagine\". Hyper-realistic amateur photography, iPhone snapshot quality",
      "quality": "medium",
      "aspect_ratio": "3:2",
      "output_format": "webp",
      "number_of_images": 1
    }
  }'
```

#### Check Prediction Status

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## 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
API rate limits ensure fair usage and prevent abuse. If you encounter a rate limit error (HTTP 429), reduce your request rate or implement exponential backoff in your retry logic.

## Error Handling
### Interpreting Error Responses
Errors are returned in JSON format, with a structure similar to:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt' is required",
    "status": 400
  }
}
```

### Common Errors
- `400 Bad Request`: Check and correct input parameters.
- `401 Unauthorized`: Ensure your API key is valid and included in the request.
- `403 Forbidden`: Verify your permissions and check API key validity.
- `429 Too Many Requests`: Implement rate limiting and exponential backoff.
- `500 Internal Server Error`: Retry after a brief pause, if the problem persists, contact support.

### Retry Strategies for Transient Errors
Implement exponential backoff for transient errors (HTTP 500). Start with a delay of 1 second, doubling the interval with each retry up to a maximum delay of 32 seconds.

## Implementation Guide
### Example Code
#### JavaScript Example

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({ version: "118f53498ea7319519229b2d5bd0d4a69e3d77eb60d6292d5db38125534dc1ca", 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 with timeout
    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; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks
  
  const startTime = Date.now();
  
  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-api-market-key": apiKey
      }
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    
    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }
    
    // Handle failure
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${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/image-generation-api-openai-gpt-image-1-5"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "118f53498ea7319519229b2d5bd0d4a69e3d77eb60d6292d5db38125534dc1ca", "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  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks
    
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        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()
        
        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        # Handle failure
        if prediction["status"] in ("failed", "canceled"):
            error_msg = prediction.get("error") or "Unknown error"
            raise Exception(f"Prediction {prediction['status']}: {error_msg}")
        
        # Wait before next poll
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL Example

```bash
# Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "118f53498ea7319519229b2d5bd0d4a69e3d77eb60d6292d5db38125534dc1ca",
    "input": {
      "prompt": "make a scene in chelsea, london in the 1970s, photorealistic, everything in focus, with tons of people, and a red double decker bus with an advertisement for \"ImageGen 1.5 on api.market\" with the subtitle \"Create what you imagine\". Hyper-realistic amateur photography, iPhone snapshot quality",
      "quality": "medium",
      "aspect_ratio": "3:2",
      "output_format": "webp",
      "number_of_images": 1
    }
  }'

# Response will contain a prediction ID like:
# {"id": "abcd1234", "status": "starting"}

# Check prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## Performance Optimization
- Choose the appropriate image quality based on your needs to optimize API unit usage and cost.
- Use lower image quality for drafts and higher quality for final outputs.
- Use async processing and proper polling intervals to handle multiple requests efficiently.

## FAQ
1. **What is the maximum number of images I can generate per request?**
   The maximum number of images you can generate per request is 10.
   
2. **Can I use the API without providing an OpenAI API key?**
   Yes, the API can be used with a proxy if you do not provide your own OpenAI API key.
   
3. **How is the content moderated?**
   The content moderation level is automatically set, or you can manually set it to "low".

4. **What happens if a prediction fails or is canceled?**
   Failed or canceled predictions are not billed.

5. **How do I check the status of my prediction?**
   Use the GET `/api/v1/magicapi/image-generation-api-openai-gpt-image-1-5/predictions/{id}` endpoint with the prediction ID.

## 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@magicapi.com.

Generate images from text with OpenAI's GPT-Image 1.5. Strong prompt adherence, optional reference images, up to 10 images per request, billed per image.