Name: Wan 2.2 – Cinematic Image Generation | $0.03/call | API.market
Brand: magicapi
SKU: api-magicapi-cinematic-text-to-image-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Cinematic Text-to-Image Generator API (Wan 2.2)

## Overview
This API enables you to generate stunning cinematic images (2 megapixel resolution) in 3–4 seconds from text prompts. Built upon advanced AI techniques, it produces photorealistic and cinematic-style images that are perfect for rapid prototyping, concept design, and creative visuals. The API is optimized for speed and efficiency, making it ideal for a wide range of use cases across various industries.

## Features
- Converts text prompts into high-quality cinematic images
- Generates images of approximately 2 megapixels in under 4 seconds
- Supports multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4, 21:9)
- Various output formats: PNG, JPG, or WEBP
- Customizable output quality (1–100) when using JPG
- Optional seed parameter for reproducible image generation
- Fast/warm “Juiced” mode option for quicker inference

## Use Cases
1. Film & Entertainment Storyboarding  
   Optimize pre-production workflows by creating quick, cinema-quality story frames from script text—speeding up collaboration between directors, screenwriters, and production teams.

2. eCommerce Product Showcases  
   Generate lifelike, visually striking product images from text ideas (e.g., “high-fashion shoe on marble background with dramatic lighting”) to quickly produce promotional materials.

3. Marketing & Advertising Mockups  
   Craft captivating ad visuals from textual concepts (e.g., “sunset beach scene with brand slogan in bold letters”). Iterate rapidly for A/B testing and campaign ideation.

4. Architectural & Interior Design Previews  
   Visualize interior or exterior spaces, lighting scenarios, and design elements by simply describing the desired look and style.

5. Educational & Training Illustrations  
   Generate diagrams, scene illustrations, and conceptual artwork for instructional design, all from descriptive text prompts.

## Visual Examples

### Overview Demo
Below is an example of a generated image using a sample prompt describing a cinematic feline subject in a nostalgic indie film setting:

Prompt (from example):  
“A cinematic, photorealistic medium shot capturing the nostalgic warmth of a mid-2000s indie film. The focus is a cat with a messy cool platinum white fur, looking directly and intently into the camera lens with a knowing smirk…”

Generated Output:
![Example cinematic cat](https://replicate.delivery/xezq/pKiB2pFgX7qgG1OxDHyMRzwvY2QPMPKPQeNqJGUAy1LrizjKA/output_246764_0.jpeg)

This showcases the API’s ability to generate photorealistic, cinematic-style images from text descriptions.

## Pricing
- Pay As You Go (PAYG): Pay only for the images you generate.  
- Every successful image generation counts as 1 API unit.  
- Checking the status of a prediction (GET /api/v1/magicapi/cinematic-text-to-image-generator/predictions/{id}) is free and doesn’t consume units.  
- No monthly subscription fees or hidden quotas—simple per-call pricing.

## API Documentation

### Base URL
All API requests should be sent to:  
```
https://prod.api.market/api/v1/magicapi/cinematic-text-to-image-generator
```

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

### Asynchronous Processing
This API performs asynchronous predictions for image generation. The workflow:

1. Send a POST request to create a prediction.  
2. Receive a prediction ID immediately in the response.  
3. Poll the GET endpoint with the prediction ID to check the current status.  
4. When status is “succeeded,” the generated image URL is provided in the output field.

Recommended polling strategy:
- Poll every 1 second.  
- Time out after 600 seconds (10 minutes).  
- If status is “starting” or “processing,” keep polling.  
- If status is “succeeded,” retrieve the output (image URL).  
- If status is “failed,” handle the error or retry if appropriate.

### Endpoints

#### 1. Create a Prediction
• URL:  
  POST /api/v1/magicapi/cinematic-text-to-image-generator/predictions  

• Description:  
  Submits a text prompt and model parameters to generate a cinematic 2MP image.

• Request Body (JSON):
```json
{
  "version": "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
  "input": {
    "seed": 246764,
    "juiced": false,
    "prompt": "A cinematic, photorealistic medium shot of ...",
    "megapixels": 2,
    "aspect_ratio": "4:3",
    "output_format": "jpg",
    "output_quality": 80
  }
}
```
- version (string): Model version ID (default shown)  
- input (object): Parameters for image generation  
  - seed (integer): Random seed for reproducibility  
  - juiced (boolean): Faster inference with additional optimizations  
  - prompt (string, required): Text description for the image  
  - megapixels (integer): 1 or 2 (default 2)  
  - aspect_ratio (string): One of [“1:1”, “16:9”, “9:16”, “4:3”, “3:4”, “21:9”]  
  - output_format (string): “png”, “jpg”, or “webp” (default jpg)  
  - output_quality (integer): (1–100), default 80, for JPG images only  

• Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/cinematic-text-to-image-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
    "input": {
      "seed": 246764,
      "juiced": false,
      "prompt": "A cinematic, photorealistic medium shot capturing the nostalgic warmth of a mid-2000s indie film...",
      "megapixels": 2,
      "aspect_ratio": "4:3",
      "output_format": "jpg",
      "output_quality": 80
    }
  }'
```

• Successful Response (Status: 201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
  "status": "starting",
  "created_at": "2025-08-17T16:56:58.541Z"
}
```

#### 2. Get Prediction Status & Results
• URL:  
  GET /api/v1/magicapi/cinematic-text-to-image-generator/predictions/{id}  

• Description:  
  Fetches the current status of a prediction and, if completed, returns the output image URL.

• Path Parameter:
- id (string): The prediction ID you received after creating the prediction.

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

• Successful Response (Status: 200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://example-link-to-output-image.com/output.jpeg",
  "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 succeeded.  
- 201 Created: Resource (prediction) successfully created.  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: API key lacks sufficient permissions.  
- 404 Not Found: The requested resource doesn’t exist.  
- 429 Too Many Requests: Rate limit exceeded; retry after a delay.  
- 500 Internal Server Error: A server-side error occurred; try again later.  
- 503 Service Unavailable: Temporary overloading or maintenance; retry later.

## Rate Limits
If you exceed certain request thresholds, you may encounter HTTP 429 (Too Many Requests). Always implement exponential backoff or some retry delay when encountering these errors.

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

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt' is required",
    "status": 400
  }
}
```
- code (string): Error classification  
- message (string): Human-readable explanation  
- status (integer): HTTP status code  

If you encounter a server-side or rate-limit error, consider retrying with an appropriate backoff strategy.

## Implementation Guide

### Example Code

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

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: "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
        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; // 10 minutes in ms
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

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

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

    const statusResult = await checkResponse.json();

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

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

    await delay(POLL_INTERVAL);
  }

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

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

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

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    payload = {
        "version": "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)
    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 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

    start_time = time.time()
    while (time.time() - start_time) < MAX_TIMEOUT:
        headers = {"x-api-market-key": API_KEY}
        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()

        if prediction["status"] == "succeeded":
            return prediction["output"]
        elif 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")
```

#### cURL
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/cinematic-text-to-image-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "16e15e913fcc71c1a5defb335ea84739f99731fa1ee17995117c7d9adc6d176c",
    "input": {
      "prompt": "A cinematic shot of a futuristic city skyline at dusk...",
      "megapixels": 2,
      "output_format": "jpg"
    }
  }'

# The response will include a prediction ID, for example:
# {
#   "id": "abcd1234",
#   "status": "starting",
#   ...
# }

# Step 2: Poll until the prediction is complete
curl -X GET "https://prod.api.market/api/v1/magicapi/cinematic-text-to-image-generator/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
# If status is "succeeded", you can find the output image URL in the "output" field.
```

### Performance Optimization
- Use meaningful prompts to reduce the need for multiple revisions.  
- Adjust your aspect ratio and megapixel preferences to fit exactly what you need.  
- If you need slightly faster results, set “juiced” to true; note that this may slightly change output quality or style.  

## FAQ
1. Can I generate multiple images at once?  
   You can make separate prediction requests in parallel, each with its own prompt or parameters.

2. Do I need to resize images afterward?  
   The model outputs 2 megapixel images (approximately 1920×1080 for 16:9 by default). Resize after retrieval if needed.

3. How do I handle extremely large prompts?  
   Keep prompts concise yet descriptive. Very large prompts may increase generation time or lead to less predictable results.

4. How do I ensure reproducible outputs?  
   Specify a numeric “seed” in your request. Using the same seed with the same parameters should produce similar results.

5. What if my request fails often?  
   Check the error messages carefully. Ensure your prompts are well-formed, valid JSON. If you encounter rate limits, implement exponential backoff.

## 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 stunning 2MP cinematic images from text prompts in 3-4 seconds. Supports multiple aspect ratios. From $0.03/call. Try it free on API.market.