Name: Instant Character – AI Avatar Generation | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-instant-character-image-avatar-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧑‍🎨 Ultra-Fast Character Image Generator API (Instant Character)

## Overview
The Ultra-Fast Character Image Generator (Instant Character) is a cutting-edge AI model powered by Tencent’s technology. It generates unique, stylized character avatars from text prompts and an input image in a matter of seconds. Perfect for gaming, media, and applications that require custom character imagery, this API combines speed, creativity, and quality in one solution.

![Example input image (subject image)](https://blog.api.market/wp-content/uploads/2026/04/instant-charachter-image-avatar.png)

## Features
- Rapid AI-based character generation: get results in seconds.  
- Highly configurable settings, including:  
  - Prompt text for describing visual or stylistic details  
  - Fine-tuning parameters (guidance scale, inference steps, etc.)  
  - Height and width adjustments for custom output dimensions  
  - Optional “lora” style transformations (e.g., ghibli_style, makoto_shinkai)  
- High-resolution outputs optimized for game assets, social media, and beyond.  
- Asynchronous processing for improved efficiency and scalability.  

## Use Cases
1. Gaming Avatars: Quickly generate in-game character portraits, NPC faces, or user avatars to enhance the gaming experience.  
2. Media & Animation: Produce stylized characters for storyboards, concept art, and animation designs for film, television, or web content.  
3. Marketing Campaigns: Create bespoke characters for brand campaigns, social media, and marketing collateral.  
4. Educational Illustrations: Generate distinct cartoon or realistic characters for e-learning modules, online courses, and interactive textbooks.  
5. App Integrations: Provide users with a seamless way to build custom avatars for profile pictures, chatbots, or any user-customization features.

## Visual Examples
Below are sample images showing how the API transforms a grayscale subject image into a stylized character avatar. The prompt provided is “a character in the library”:

### Input Image
![Grayscale face input](https://blog.api.market/wp-content/uploads/2026/04/instant-charachter-image-avatar.png)

### Output Image
![Ghibli-style library character](https://blog.api.market/wp-content/uploads/2026/04/output-ghibli.png)

These images demonstrate how a simple headshot can be transformed into a stylized result based on your prompt and optional style settings.

## Pricing
• 1 API unit = 1 image processed.  
• GET requests for checking prediction status (GET /api/v1/magicapi/instant-character-image-avatar-generator/predictions/{id}) are free.  
• Flexible pricing tiers are available based on usage volume. Contact us to discuss your needs.

## API Documentation

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

### Authentication
Include your API key in every request:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
If your API key is missing or invalid, you will receive a 401 Unauthorized response.

### Asynchronous Processing
Instant Character uses asynchronous processing for image generation. The process flow is:

1. Submit a request with your input (subject image, prompt, and any other parameters)  
2. Receive a response containing a prediction ID  
3. Poll the status endpoint using the returned ID  
4. Once the status becomes "succeeded," retrieve the result from the output field  

We recommend:
- Polling every 1 second  
- A maximum timeout of 600 seconds (10 minutes)  
- Checking the status field for completion, error, or timeout  

### Endpoints

#### 1) Create a Prediction
• Endpoint:  
  POST /api/v1/magicapi/instant-character-image-avatar-generator/predictions  
• Description:  
  Creates a new prediction request using the Instant Character model.  

Example Request (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/instant-character-image-avatar-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "df5eed34fa9c812acf62d3ca79874daf9b5e78c2bee11f4ada182a55dd5c1712",
    "input": {
      "lora": "ghibli_style",
      "seed": -1,
      "width": 768,
      "height": 1344,
      "prompt": "a character in the library",
      "subject_image": "https://blog.api.market/wp-content/uploads/2026/04/instant-charachter-image-avatar.png",
      "guidance_scale": 3.5,
      "num_inference_steps": 28
    }
  }'
```

Example Successful Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "df5eed34fa9c812acf62d3ca79874daf9b5e78c2bee11f4ada182a55dd5c1712",
  "status": "starting",
  "created_at": "2025-05-18T08:21:08.615Z"
}
```

#### 2) Get Prediction Status/Result
• Endpoint:  
  GET /api/v1/magicapi/instant-character-image-avatar-generator/predictions/{id}  
• Description:  
  Checks the status of a previously created prediction request. Also returns the output if the prediction is complete.

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

Example Successful Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/04/output-ghibli.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"
}
```

In case of failure:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "failed",
  "error": "Invalid parameters",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:00:30.000Z"
}
```

## Status Codes
- 200 OK: The request was successful.  
- 201 Created: The resource was created successfully.  
- 400 Bad Request: Invalid 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 does not exist.  
- 429 Too Many Requests: You have exceeded your rate limit; try again later.  
- 500 Internal Server Error: An error occurred on the server.  
- 503 Service Unavailable: The service is temporarily unavailable or undergoing maintenance.  

## Rate Limits
The API enforces rate limits based on your plan tier. If you exceed your allowed requests, you will receive an HTTP 429 status. Reduce your request frequency or upgrade your plan to resolve this.

## Error Handling
If an error occurs, you will typically receive a JSON response with details:

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

Best practices:
- Validate all required fields before sending requests.  
- Handle 400 errors by adjusting input parameters.  
- Retry or report 500-series error codes.  
- Implement exponential backoff or short delays before retrying if necessary.

## Implementation Guide
Follow these steps to integrate the API into your stack:

### Example Code

#### JavaScript (Node.js)
```javascript
const fetch = require("node-fetch");

const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/instant-character-image-avatar-generator";

async function createAndWaitForPrediction(inputData) {
  try {
    // 1. Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "df5eed34fa9c812acf62d3ca79874daf9b5e78c2bee11f4ada182a55dd5c1712",
        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; // 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-magicapi-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");
}
```

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

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

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }

    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "df5eed34fa9c812acf62d3ca79874daf9b5e78c2bee11f4ada182a55dd5c1712",
            "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"]
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 10 minutes
    POLL_INTERVAL = 1  # 1 second

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        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":
            raise Exception(f"Prediction failed: {prediction.get('error', 'Unknown error')}")

        time.sleep(POLL_INTERVAL)

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

#### cURL
```bash
# 1. Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/instant-character-image-avatar-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "df5eed34fa9c812acf62d3ca79874daf9b5e78c2bee11f4ada182a55dd5c1712",
    "input": {
      "prompt": "A fantasy wizard with a glowing staff",
      "subject_image": "https://example.com/your_subject_image.png"
    }
  }'

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

# 2. Check the status until "status" is "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/instant-character-image-avatar-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Use higher-level caching if your application requests similar prompts repeatedly (although each generation will still count as an API usage).  
- Adjust the inference parameters (num_inference_steps, guidance_scale) to balance speed and quality.  
- Provide well-detailed but concise prompts to get the best possible results.  

## FAQ
• How long does each request take?  
  – Most images generate in a few seconds, depending on the complexity of your prompt.  

• Can I use larger image resolutions?  
  – Yes, but keep in mind that higher resolution increases both processing time and resource usage.  

• What if the generation fails?  
  – You will receive a "failed" status. Check the "error" field for more details.  

• Are there any style presets I can apply?  
  – Yes, you can specify “ghibli_style” or “makoto_shinkai” in the “lora” field.

## 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 unique, stylized character avatars from text prompts and a reference image. Powered by Tencent's AI. From $0.05/call. Try it free on API.market.