Name: Gen-4 Turbo – AI Image Generation | $0.02/call | API.market
Brand: magicapi
SKU: api-magicapi-ultra-fast-reference-image-generator-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# ⚡ Ultra-Fast Reference Image Generator API (Gen-4 Turbo)

## Overview
Welcome to the Ultra-Fast Reference Image Generator API (Gen-4 Turbo). This AI-powered API transforms your text prompts and up to three reference images into unique, customized visuals—at lightning speed. Compared to the standard Gen-4 Image model, Gen-4 Turbo is 2.5x faster and more cost-effective, helping you capture every angle with fewer resources. Simply provide text descriptions along with reference images and optional tags to generate striking images that can enhance product marketing, creative storytelling, and more.

## Features
- **2.5x Faster Generation**: Get your images in a fraction of the time compared to standard Gen-4 models.  
- **Reference Images Supported**: Supply up to 3 reference images for more accurate or stylized results.  
- **Flexible Prompting**: Use custom prompts with tags (@man, @woman, etc.) that correspond to your reference images.  
- **Cheaper Operations**: Take advantage of lower cost per call, making AI-driven image generation more accessible.  
- **Custom Resolutions & Aspect Ratios**: Choose from common resolutions (e.g., 720p and 1080p) and aspect ratios (e.g., 16:9, 4:3, etc.).  

## Use Cases
Below are some practical, industry-focused use cases for Gen-4 Turbo:

1. **E-Commerce Product Shots**  
   Quickly generate lifestyle or multiple-angle product images for online stores. Ideal for fashion, tech gadgets, or cosmetics, this speeds up product photography workflows.

2. **Architectural Visualizations**  
   Provide references of building materials or styles, combined with text prompts describing the desired environment (e.g., “modern open-concept living room”), to get different interior/exterior visuals from the same references.

3. **Marketing Campaigns**  
   Tailor images to specific audiences by reusing brand elements or characters from reference images—perfect for personalized ads or social media campaigns.

4. **Film & Media Storyboarding**  
   Generate quick storyboards using reference photos of actors or sets. Use up to 3 references (actor headshots, setting images, etc.) and text prompts describing the action or mood.

5. **Character Design for Gaming**  
   Provide partial sketches or concept art, then supply prompts describing character attributes (e.g., “fantasy knight with glowing sword, @character_references for face and armor style”).

These examples illustrate the speed and flexibility of integrating Gen-4 Turbo into workflows across multiple industries.

## Visual Examples

### Example from Input References to Final Output
Below is an example of references and final output defined in the OpenAPI schema. The references are labeled so you can see how they’re used in the text prompt with tags.

- Input Reference Images  
  ![Reference image of a woman](https://replicate.delivery/pbxt/NW3jTsbeAGmmIdOvQ5Ks2Dh6wAWAwBj9FLup7GmkmKZIzVp7/w99em95b01rmc0cqrny8chf49w-1.jpg)  
  ![Reference image of a man](https://replicate.delivery/pbxt/NW3jTS88toyUUsCurdKfDgWVfXLXWmBsGbbG6jipbMFgpyT2/psjdbkzgm1rmc0cqrnysbg93cm.jpg)

- Sample Prompt  
  “a close up portrait of @woman and @man driving fast in a red 1980s sports car”

- Example Output  
  ![Example generated image from the described scenario](https://replicate.delivery/xezq/mV82397wvrIxDlCV0AMe3v6MSoRh4xEa8a0eSDr7ipH0q3JVA/tmpuwbggnyb.png)

This illustrates how each reference tag matches a specific image, enabling the AI to accurately integrate those elements into the generated result.

## Pricing
• Pay As You Go (PAYG) – only pay for what you use.  
• 1 API unit = 1 image processed.  
• Free GET requests to check status (GET /api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions/{id}) – these do NOT consume any units.  
• No monthly subscription fees or usage limits – simple per-call pricing.

## API Documentation

### Base URL
All requests to this API should be made to:

```
https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api
```

### Authentication
Use your API key to authenticate. Include the following header in requests:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes predictions asynchronously. The standard workflow:

1. Create a prediction via a POST request (you’ll get a unique ID).  
2. Poll the status with a GET request using that ID.  
3. Continue polling until the status changes to “succeeded” or “failed.”  

Keep these recommendations in mind:
- Poll every 1 second.  
- Use a maximum timeout of 600 seconds (10 minutes).  
- If `status` becomes `succeeded`, retrieve and utilize the `output`.  
- If the API returns `failed` or the operation times out, handle the error.

### Endpoints

#### 1) Create a Prediction
• **HTTP Method**: `POST`  
• **Path**: `/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions`  
• **Description**: Submits your prompt and reference images for inference with Gen-4 Turbo.

Example request:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "e724bfa0ed4865c0d543acfe5abdfbeeffa6743769504e9e23d0e309b3a68174",
    "input": {
      "prompt": "a close up portrait of @woman and @man driving fast in a red 1980s sports car",
      "resolution": "1080p",
      "aspect_ratio": "4:3",
      "reference_tags": ["woman", "man"],
      "reference_images": [
        "https://replicate.delivery/pbxt/NW3jTsbeAGmmIdOvQ5Ks2Dh6wAWAwBj9FLup7GmkmKZIzVp7/w99em95b01rmc0cqrny8chf49w-1.jpg",
        "https://replicate.delivery/pbxt/NW3jTS88toyUUsCurdKfDgWVfXLXWmBsGbbG6jipbMFgpyT2/psjdbkzgm1rmc0cqrnysbg93cm.jpg"
      ]
    }
  }'
```

Example response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "e724bfa0ed4865c0d543acfe5abdfbeeffa6743769504e9e23d0e309b3a68174",
  "status": "starting",
  "created_at": "2025-08-17T18:09:43.034Z"
}
```

#### 2) Retrieve Prediction Status & Output
• **HTTP Method**: `GET`  
• **Path**: `/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions/{id}`  
• **Description**: Fetches the current status of the prediction, plus output if ready.

Example request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Example response (if status = succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/xezq/mV82397wvrIxDlCV0AMe3v6MSoRh4xEa8a0eSDr7ipH0q3JVA/tmpuwbggnyb.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 completed successfully.  
- **201 Created** – Prediction was successfully initiated (for POST create).  
- **400 Bad Request** – Malformed request or invalid parameters.  
- **401 Unauthorized** – Missing or invalid API key.  
- **403 Forbidden** – Valid API key, but lack of necessary permissions.  
- **404 Not Found** – The specified resource or prediction ID does not exist.  
- **429 Too Many Requests** – Rate limit exceeded; try again after a pause.  
- **500 Internal Server Error** – A server-side error occurred.  
- **503 Service Unavailable** – Server is temporarily unavailable; try again later.

In every case, check the response body for error details and handle accordingly.

## Rate Limits
While specific numeric rate limits aren’t provided here, requests may be subject to fairness-based controls. If you receive a 429 (Too Many Requests) response, wait briefly and retry. Use best practices such as exponential backoff.

## Error Handling
Whenever an error occurs, the API returns a JSON payload describing the issue. For example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt' is missing",
    "status": 400
  }
}
```
- Always check the `error` object for meaningful messages.
- Implement retry logic or adjust request parameters as appropriate.
- If you repeatedly get 400-level errors, verify your input parameters.

## Implementation Guide

Below are code snippets in JavaScript, Python, and cURL illustrating best practices with asynchronous polling, error handling, and timeouts.

### Example Code

#### JavaScript (Node.js) with Fetch
```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-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: "e724bfa0ed4865c0d543acfe5abdfbeeffa6743769504e9e23d0e309b3a68174",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error (create): ${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
  const startTime = Date.now();

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

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

    const prediction = await response.json();
    const { status, output, error } = prediction;

    if (status === "succeeded") {
      return output;
    } else if (status === "failed") {
      throw new Error(`Prediction failed: ${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 futuristic city skyline at sunset" })
//   .then(output => console.log("Generation Output URL:", output))
//   .catch(err => console.error(err));
```

#### Python (Requests)
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api"
VERSION_ID = "e724bfa0ed4865c0d543acfe5abdfbeeffa6743769504e9e23d0e309b3a68174"

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": VERSION_ID, "input": input_data}
    )

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

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

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

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds
    POLL_INTERVAL = 1  # 1 second
    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 (status): {response.status_code} {response.text}")

        prediction = response.json()
        status = prediction.get("status")
        output = prediction.get("output")
        error = prediction.get("error")

        if status == "succeeded":
            return output
        elif status == "failed":
            raise Exception(f"Prediction failed: {error or 'Unknown error'}")

        time.sleep(POLL_INTERVAL)

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

# Example usage:
# result_url = create_and_wait_for_prediction({
#     "prompt": "a painting of a calm forest creek at dawn"
# })
# print("Generated image URL:", result_url)
```

#### cURL (CLI)
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "e724bfa0ed4865c0d543acfe5abdfbeeffa6743769504e9e23d0e309b3a68174",
    "input": {
      "prompt": "a painting of a calm forest creek at dawn",
      "resolution": "720p"
    }
  }'

# You'll get a response containing the prediction "id", e.g.:
# {
#   "id": "abcd1234",
#   "status": "starting",
#   ...
# }

# Step 2: Check status in a loop (pseudo-code).
# Replace "abcd1234" with the actual ID and repeat until status is "succeeded".
curl -X GET "https://prod.api.market/api/v1/magicapi/ultra-fast-reference-image-generator-api/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- **Batch Requests**: Combine similar tasks into a single session to reduce overhead.  
- **Use Reference Images Wisely**: Provide only up to three references that best cover your use case. Too many references can increase complexity without improving results.  
- **Run Parallel Predictions**: If you have multiple prompts, you can dispatch several at once (within your rate limits).

## FAQ
1. **How many reference images can I upload?**  
   Up to three. This helps the model provide more accurate visuals without overcomplicating the request.

2. **What is the maximum allowed resolution?**  
   Currently, 1080p is supported in the examples. Choose from 720p or 1080p.

3. **How quickly can I expect a response?**  
   Typically, generation is 2.5x faster than standard Gen-4. However, processing time varies with complexity and load.

4. **Are GET requests to check status billed?**  
   No, status-check requests (GET /predictions/{id}) are free and do not consume units.

5. **What if the API returns an error after waiting?**  
   Check the error message to see if your prompt or reference images need adjustments before retrying.

## 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 custom visuals from text and up to 3 reference images. 2.5x faster than standard models. $0.02/call. Try it free on API.market.

Gen-4 Turbo – AI Image Generation | $0.02/call | API.market

⚡ Ultra-Fast Reference Image Generator API (Gen-4 Turbo)

PAYG

MagicAPI

The Ultra-Fast Reference Image Generator API (Gen-4 Turbo) is impressive—blazing fast, cost-effective, and perfect for creating customized visuals from text and references. A must-have for marketers, creators, and businesses who want quality results in no time.