Name: Imagen 4 Ultra – Photorealistic Images | $0.07/call | API.market
Brand: magicapi
SKU: api-magicapi-ultra-high-quality-text-to-image-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 🖼️ Ultra-Quality Text-to-Image Generator API (Imagen 4 Ultra)

## Overview
The Ultra-Quality Text-to-Image Generator API (Imagen 4 Ultra) takes text prompts and produces photorealistic, hyper-detailed images with remarkable fidelity and premium quality. It is designed for scenarios where maximum image realism and detail are more important than speed or cost.

This API is ideal if you need high-end visual outputs—ranging from product imagery to high-quality concept art—in industries such as advertising, design, gaming, and more.

## Features
- Generate photorealistic images from textual descriptions.  
- Support for flexible aspect ratios (e.g., 1:1, 16:9, 9:16, etc.).  
- Optional safety filters for controlling content strictness.  
- Downloadable outputs in JPG or PNG format.  
- Handles complex, multi-line prompts with advanced text recognition.  

## Use Cases
1. Marketing & Advertising: Generate high-resolution, impactful visuals for ad campaigns that demand photorealistic quality.  
2. Film & Media: Create concept art and storyboarding visuals with cinematic detail to communicate your vision effectively.  
3. E-Commerce Product Shoots: Craft realistic product images without the cost of physical shoots or elaborate setups.  
4. Architectural Visualizations: Generate striking, lifelike renders from textual descriptions of buildings, interiors, and landscapes.  
5. Game Development: Produce concept art or in-game textures with ultra-high-quality detail to keep up with next-gen visual demands.

## Visual Examples

### Example Output Image
Below is an example output image URL provided in the OpenAPI schema under successful prediction response. Here, the API was prompted to produce a cinematic, photorealistic portrait image with specific aesthetic details:

![Sample Output Image for a cinematic, photorealistic look](https://blog.api.market/wp-content/uploads/2025/07/apI_market_imagen_4.jpg)

In the prompt used for this image, the user asked for:
"The photo: Create a cinematic, photorealistic medium shot capturing the nostalgic warmth of a mid-2000s indie film. The focus is a young woman with a sleek, straight bob haircut in cool platinum white with freckled skin, looking directly and intently into the camera lens with a knowing smirk, her head is looking up slightly. She wears an oversized band t-shirt that says 'Imagen 4 Ultra' in huge stylized text over a long-sleeved striped top and simple silver stud earrings..."

This output demonstrates the API’s ability to respect intricate lighting, background blur, lens flare, shallow depth-of-field, and subtle text details.


## API Documentation

### Base URL
All requests should be directed to:
```
https://prod.api.market/api/v1/magicapi/ultra-high-quality-text-to-image-api
```

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

### Asynchronous Processing
When a prediction is created, the request will return a prediction ID. The image generation operation runs in the background. You must poll the prediction status endpoint until the status is "succeeded" (or "failed").

Workflow:
1. POST a prediction request.  
2. Receive a prediction ID.  
3. Poll the GET /predictions/{id} endpoint.  
4. Continue polling until the status is "succeeded" or "failed".  
5. If succeeded, retrieve the result from the "output" field.

We recommend:  
- Poll once every second.  
- Implement a timeout of 600 seconds (10 minutes).  
- Stop polling if the status is "failed" or if the timeout is reached.

### Endpoints

#### 1. Create a Prediction
POST /api/v1/magicapi/ultra-high-quality-text-to-image-api/predictions

• Description: Submits a new text-to-image request.

• Request Body (JSON):
```json
{
  "version": "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
  "input": {
    "prompt": "Your text prompt here",
    "aspect_ratio": "1:1",
    "output_format": "jpg",
    "safety_filter_level": "block_only_high"
  }
}
```
- version (string): Model version ID.  
- input (object):  
  - prompt (string): Descriptive text for the image.  
  - aspect_ratio (string): One of [1:1, 9:16, 16:9, 3:4, 4:3].  
  - output_format (string): Either "jpg" or "png".  
  - safety_filter_level (string): "block_low_and_above", "block_medium_and_above", or "block_only_high".

• Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
  "status": "starting",
  "created_at": "2025-07-11T10:08:50.900Z"
}
```
- id (string): Unique prediction identifier.  
- version (string): The model version used.  
- status (string): Usually "starting" or "processing".  
- created_at (string): Timestamp of creation.

##### cURL Example
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-high-quality-text-to-image-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
    "input": {
      "prompt": "A detailed cinematic image prompt",
      "aspect_ratio": "16:9",
      "output_format": "jpg",
      "safety_filter_level": "block_only_high"
    }
  }'
```

#### 2. Get Prediction Status & Results
GET /api/v1/magicapi/ultra-high-quality-text-to-image-api/predictions/{id}

• Description: Retrieves the current status of a prediction, and returns the output image URL once the generation has succeeded.

• Path Parameter:
- id (string): The prediction identifier returned by the Create Prediction endpoint.

• Response (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://example.com/output-image.jpg",
  "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"
}
```
- id (string): Unique prediction identifier.  
- status (string): "starting", "processing", "succeeded", "failed", or "canceled".  
- output (string): URL to the generated image if successful.  
- error (string): Error message if the operation fails.  
- created_at (string): When the prediction was initially queued.  
- started_at (string): When processing began.  
- completed_at (string): When the generation process finished.

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

## Status Codes
- 200 OK: Request succeeded.  
- 201 Created: The prediction or resource was successfully created.  
- 400 Bad Request: Invalid input data or parameters.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: The API key is valid but lacks sufficient permissions.  
- 404 Not Found: The requested resource (prediction ID) does not exist.  
- 429 Too Many Requests: You have exceeded the rate limit for this API.  
- 500 Internal Server Error: A problem occurred on the server.  
- 503 Service Unavailable: Temporary overloading or maintenance of the server.

## Rate Limits
Depending on usage plans, the API may enforce rate limits. If you hit a 429 Too Many Requests error, you should back off and retry after a short delay. You can monitor your API usage and quotas through your API.market dashboard.

## Error Handling
When errors occur, the API attempts to provide meaningful messages in a JSON structure. For instance:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Parameter 'prompt' is required",
    "status": 400
  }
}
```
- code: A brief string identifying the error type.  
- message: A descriptive message explaining the error.  
- status: HTTP status code to help you handle the error programmatically.

For transient errors (e.g., 503 Service Unavailable), implement a retry strategy with exponential backoff.

## Implementation Guide
Below is sample code to illustrate how you can integrate and properly handle asynchronous predictions.

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

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: "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
        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 a 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
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    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();

    if (prediction.status === "succeeded") {
      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");
}

// Example usage:
// createAndWaitForPrediction({
//   prompt: "A lifelike illustration of a futuristic cityscape with neon lights",
//   aspect_ratio: "16:9",
//   output_format: "jpg"
// })
// .then(outputUrl => console.log("Image URL:", outputUrl))
// .catch(err => console.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-high-quality-text-to-image-api"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    payload = {
        "version": "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
        "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"]
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds = 10 minutes
    POLL_INTERVAL = 1
    start_time = time.time()

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

        prediction = response.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        if prediction["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")

# Example usage:
# result_url = create_and_wait_for_prediction({
#     "prompt": "A hyper-detailed, photorealistic painting of a mysterious forest lit by moonlight",
#     "aspect_ratio": "4:3",
#     "output_format": "png"
# })
# print("Generated image URL:", result_url)
```

### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-high-quality-text-to-image-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6fd21fa98bbcc95e9749ed9800daabc3e1e88d9e5ca85025f33dc0be3322570b",
    "input": {
      "prompt": "A futuristic cityscape at night with holographic billboards",
      "aspect_ratio": "16:9",
      "output_format": "jpg"
    }
  }'

# Step 2: Check status until it is "succeeded" or "failed"
curl -X GET "https://prod.api.market/api/v1/magicapi/ultra-high-quality-text-to-image-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Use shorter prompts if feasible to reduce processing time.  
- Poll the status in reasonable intervals (1 second recommended).  
- Cancel or handle early if the operation takes too long (> 10 minutes).  

## FAQ
1. Can I generate multiple images in one call?  
   - Each request produces one output image. You can submit multiple requests in parallel.
2. Are there language or length limits on prompts?  
   - There are no strict language constraints. However, extremely long prompts may impact processing speed.
3. What if my image prompt is disallowed by the safety filter?  
   - Some prompts may be blocked. You can adjust the safety_filter_level for more or less restrictive handling.
4. How quickly can I get a result?  
   - Typical generation times range from a few seconds to a minute or more, depending on server load and image complexity.

## 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 hyper-detailed, photorealistic images from text prompts with remarkable fidelity. Supports flexible aspect ratios. Try it free on API.market.