Name: Ideogram – Consistent Characters | $0.12/call | API.market
Brand: magicapi
SKU: api-magicapi-consistent-character-generator-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧑‍🎨 Consistent Character Generator API (Ideogram-AI)

## Overview
The Consistent Character Generator API enables you to easily produce visually consistent characters from a single reference image. You can specify various parameters to generate characters in unique styles, or integrate (inpaint) the character into existing scenes. This is ideal for comics, games, digital storytelling, and more.

## Features
- Create consistent characters from a single reference image.  
- Flexible styling: Choose from realistic, fiction, or automatically selected styles.  
- Inpainting functionality: Insert or modify your character directly onto an existing image using a mask.  
- Various resolution and aspect ratio options for different creative needs.  
- Asynchronous processing with simple polling to fetch results.  

## Use Cases
1. Comics & Graphic Novels: Rapidly generate character art expected to be visually consistent across different panels and scenes.  
2. Game Development: Quickly build a library of NPC or main character variations by adjusting style but retaining consistent character features.  
3. Marketing & Advertising: Create branded mascots or spokesperson characters that appear in multiple promotional assets with uniform characteristics.  
4. Digital Storytelling & Animations: Produce multiple poses and scenarios for a singular character, streamlining workflows across different episodes or chapters.  
5. E-Learning & Instructional Content: Design consistent characters to guide learners throughout the curriculum, maintaining familiarity while tailoring context.  

## Visual Examples

### Example Character Reference Image
Below is an example of a reference image you might use to define your character’s core attributes:

![Example of a character reference image](https://replicate.delivery/pbxt/NUKxQppU8C2sCfleK0lGVI0vt9P3swKz3MnKs1z9fnHkdAV2/0_1.webp)

### Example Masked Inpainting Image
An example image URL that might be used for inpainting or masking:

![Black and white mask illustration](https://example.com/image.jpg)

### Example Output
Here is an example of an output image where the API has generated a new scene or style while maintaining the character’s key features:

![Generated image from the reference character](https://replicate.delivery/xezq/p1HmPahgsjY0BVE2IwsztADHheUFDLc5PX8101KL5PdUaIkKA/tmpzgo26mwp.png)

## Pricing
- Pay As You Go (PAYG): Pay only for what you use.  
- 1 API unit = 1 image processed.  
- GET requests to check prediction status (GET /api/v1/magicapi/consistent-character-generator-api/predictions/{id}) are free and do not count toward API unit usage.  
- No monthly subscription fees or usage limits.  

## API Documentation

### Base URL
All API requests should be made to:  
```
https://prod.api.market/api/v1/magicapi/consistent-character-generator-api
```

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

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

1. Make a POST request to create a prediction.  
2. The response includes a prediction ID.  
3. Poll the GET endpoint with the prediction ID to check the status.  
4. Continue polling until status is "succeeded" (or "failed").  

Plan for:  
- A polling interval of 1 second.  
- A maximum timeout of 600 seconds (10 minutes).  
- Handling of "starting" and "processing" statuses until they finalize to "succeeded" or "failed."  

### Endpoints

#### POST /api/v1/magicapi/consistent-character-generator-api/predictions
Creates a prediction for character generation or inpainting.

Example Request (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/consistent-character-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "252375c5cd35d4bf7aa0f2b615a32b1646373e28223f184f92fc8dc0a45721ac",
    "input": {
      "prompt": "a close up photo of a woman in a fashion magazine photoshoot",
      "character_reference_image": "https://replicate.delivery/pbxt/NUKxQppU8C2sCfleK0lGVI0vt9P3swKz3MnKs1z9fnHkdAV2/0_1.webp"
    }
  }'
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "252375c5cd35d4bf7aa0f2b615a32b1646373e28223f184f92fc8dc0a45721ac",
  "status": "starting",
  "created_at": "2025-08-17T09:47:21.818Z"
}
```

#### GET /api/v1/magicapi/consistent-character-generator-api/predictions/{id}
Retrieves the status and result of an ongoing prediction.

Example Request (cURL):
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/consistent-character-generator-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Example Response (JSON) when succeeded:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/xezq/p1HmPahgsjY0BVE2IwsztADHheUFDLc5PX8101KL5PdUaIkKA/tmpzgo26mwp.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 successful.  
- 201 Created: A new resource (prediction) was 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: The requested resource (prediction) does not exist.  
- 429 Too Many Requests: Rate limit exceeded. Wait and retry later.  
- 500 Internal Server Error: A server-side error occurred.  
- 503 Service Unavailable: Service is temporarily unavailable.  

## Rate Limits
The Consistent Character Generator API enforces per-minute rate limits. If you exceed these limits, you’ll receive a 429 Too Many Requests response. If you plan on high-volume usage, implement retry logic or contact support for higher throughput.

## Error Handling
In case of errors, the API returns JSON with an error message:

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

Common issues:  
- Missing required parameters (e.g., "prompt" or "character_reference_image").  
- Invalid API key.  
- Invalid or unreachable image URLs.  

Implement a retry strategy for transient errors (429, 503), with exponential backoff to avoid rapidly resubmitting failed requests.

## Implementation Guide

### Example Code

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

async function createAndWaitForPrediction(inputData) {
  try {
    // 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: "252375c5cd35d4bf7aa0f2b615a32b1646373e28223f184f92fc8dc0a45721ac",
        input: inputData
      })
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    const predictionId = prediction.id;
    
    // 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 status checks
  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"}`);
    }
    
    await delay(POLL_INTERVAL);
  }

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

// Example usage:
// createAndWaitForPrediction({ 
//   prompt: "a heroic knight on a medieval battlefield",
//   character_reference_image: "https://replicate.delivery/pbxt/NUKxQppU8C2sCfleK0lGVI0vt9P3swKz3MnKs1z9fnHkdAV2/0_1.webp"
// })
//   .then(result => console.log("Result:", result))
//   .catch(console.error);
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/consistent-character-generator-api"

def create_and_wait_for_prediction(input_data):
    # 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": "252375c5cd35d4bf7aa0f2b615a32b1646373e28223f184f92fc8dc0a45721ac",
            "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"]
    
    # 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
    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"]
        
        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 = create_and_wait_for_prediction({
#     "prompt": "a heroic knight on a medieval battlefield",
#     "character_reference_image": "https://replicate.delivery/pbxt/NUKxQppU8C2sCfleK0lGVI0vt9P3swKz3MnKs1z9fnHkdAV2/0_1.webp"
# })
# print("Result:", result)
```

#### cURL
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/consistent-character-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "252375c5cd35d4bf7aa0f2b615a32b1646373e28223f184f92fc8dc0a45721ac",
    "input": {
      "prompt": "a close up photo of a woman in a fashion magazine photoshoot",
      "character_reference_image": "https://replicate.delivery/pbxt/NUKxQppU8C2sCfleK0lGVI0vt9P3swKz3MnKs1z9fnHkdAV2/0_1.webp"
    }
  }'

# Example response:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll for prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/consistent-character-generator-api/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Repeat until status is "succeeded" or "failed"
```

### Performance Optimization
- Minimize complex prompts. Shorter, concise prompts can speed up generation.  
- Use a reasonable polling interval (1 second) and abort if no response after 10 minutes to avoid extra costs.

## FAQ
1. How long does each prediction take?  
   - Processing time varies by prompt complexity. Expect a few seconds to a couple of minutes.  

2. Is there a limit on the resolution or aspect ratio I can use?  
   - You can set specific resolutions or aspect ratios within the predefined enumerations. For inpainting, the API reads the resolution from your supplied image.  

3. Do I pay for failed predictions?  
   - Processing costs are applied per image request; check your usage in your API.market account.  

4. Can I integrate the output with my existing pipeline?  
   - Yes, just retrieve the final output URL when the status is "succeeded" and use it wherever needed.  

5. How do I ensure the character remains consistent?  
   - Provide a clear character reference image, and supply prompts that guide style changes without altering identifying traits of the character.  

## 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 consistent characters from a single reference image. Inpaint characters into scenes. From $0.12/call. Try it free on API.market.

Ideogram – Consistent Characters | $0.12/call | API.market

🧑‍🎨 Consistent Character Generator API (Ideogram-AI)

PAYG

MagicAPI

Create visually consistent characters from a single reference image in diverse styles—perfect for comics, games, and storytelling with rapid, high-quality resul