Name: InstantID Artistic Identity-Preserving Portrait API
Brand: magicapi
SKU: api-magicapi-identity-preserving-art-generator-grandlineai-instant-id-artistic
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Identity-Preserving Artistic Portrait Generator API (grandlineai InstantID Artistic)

## Overview
InstantID Artistic generates new, stylized images of a person from one face photo, keeping their identity. Its developer describes it as InstantID, zero-shot identity-preserving generation in seconds, using Dreamshaper-XL as the base model to encourage artistic generations.

Send a face photo as `image` and a text `prompt` describing the scene and art style. The model returns the URL of one JPEG image of that person in the new style. No training or fine-tuning per person is needed.

## Features
- **Identity from one photo**: the face in `image` is carried into the generated picture.
- **Artistic base model**: built on Dreamshaper-XL for illustrated, painted and anime-like looks.
- **Prompt and negative prompt**: describe the scene and style in `prompt`, list what to avoid in `negative_prompt`.
- **Output size**: `width` and `height` from 512 to 2048 px (default 640 x 640).
- **Identity and pose strength**: `ip_adapter_scale` (0 to 1, default 0.8) sets how strongly the face identity is applied; `controlnet_conditioning_scale` (0 to 1, default 0.8) sets how strongly the face structure from the photo guides the image.
- **Sampling controls**: `num_inference_steps` (1 to 500, default 30) and `guidance_scale` (1 to 50, default 5).

## Use Cases
1. **Stylized portraits**: anime, comic, painterly or poster-style versions of a person.
2. **Profile and avatar art**: illustrated avatars from a single selfie.
3. **Creative campaigns and gifts**: consistent artistic portraits of the same consenting person across many styles.

## Visual Examples
### Example Input
![InstantID Artistic example input: an AI-generated face portrait](https://blog.api.market/wp-content/uploads/2026/10/ip-adapter-faceid-input-api-market.png)

Prompt: "80's anime screencap, woman wearing a denim jacket, artistic rendition with wide brush strokes, anime comic"

Negative prompt: "cgi, render, bad quality, worst quality, text, signature, watermark, extra limbs, unaestheticXL_hk1, negativeXL_D"

Settings: `width` `640`, `height` `640`, `guidance_scale` `5`, `ip_adapter_scale` `0.8`, `num_inference_steps` `30`, `controlnet_conditioning_scale` `0.8`.

### Example Output
![InstantID Artistic output for the example face photo and the 80s anime screencap prompt](https://blog.api.market/wp-content/uploads/2026/10/instant-id-artistic-output-nmmknbkp-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image with the face to keep (jpeg, png, gif or webp) |
| `prompt` | string | No | `analog film photo of a man. faded film, desaturated, 35mm photo, grainy, vignette, vintage, Kodachrome, Lomography, stained, highly detailed, found footage, masterpiece, best quality` |  | Input prompt |
| `negative_prompt` | string | No | `""` |  | Input negative prompt |
| `width` | integer | No | `640` | 512 to 2048 | Width of output image |
| `height` | integer | No | `640` | 512 to 2048 | Height of output image |
| `ip_adapter_scale` | number | No | `0.8` | 0 to 1 | Scale for IP adapter |
| `controlnet_conditioning_scale` | number | No | `0.8` | 0 to 1 | Scale for ControlNet conditioning |
| `num_inference_steps` | integer | No | `30` | 1 to 500 | Number of denoising steps |
| `guidance_scale` | number | No | `5` | 1 to 50 | Scale for classifier-free guidance |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.024 per API unit.
- **1 API unit = 1 successful request with up to 22 seconds of processing.** A longer job bills one more unit for each started block of 22 seconds (for example, 50 seconds of processing is 3 units, $0.072).
- Processing time grows with `width`, `height` and `num_inference_steps`.
- **Example cost**: the example request (640 x 640, 30 steps) took 17.2 seconds of processing, which is 1 unit, so $0.024.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/identity-preserving-art-generator-grandlineai-instant-id-artistic`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/identity-preserving-art-generator-grandlineai-instant-id-artistic/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "9cad10c7870bac9d6b587f406aef28208f964454abff5c4152f7dec9b0212a9a",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/10/ip-adapter-faceid-input-api-market.png",
      "width": 640,
      "height": 640,
      "prompt": "80'\''s anime screencap, woman wearing a denim jacket, artistic rendition with wide brush strokes, anime comic",
      "guidance_scale": 5,
      "negative_prompt": "cgi, render, bad quality, worst quality, text, signature, watermark, extra limbs, unaestheticXL_hk1, negativeXL_D",
      "ip_adapter_scale": 0.8,
      "num_inference_steps": 30,
      "controlnet_conditioning_scale": 0.8
    }
  }'
```

Response (201 Created):
```json
{
  "id": "nmmknbkp01rmy0d1f1etrctv88",
  "version": "9cad10c7870bac9d6b587f406aef28208f964454abff5c4152f7dec9b0212a9a",
  "status": "starting",
  "created_at": "2026-10-26T13:19:14.060Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/identity-preserving-art-generator-grandlineai-instant-id-artistic/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "nmmknbkp01rmy0d1f1etrctv88",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/instant-id-artistic-output-nmmknbkp-api-market.jpg",
  "error": null,
  "created_at": "2026-10-26T13:19:14.060Z",
  "started_at": "2026-10-26T13:21:26.920Z",
  "completed_at": "2026-10-26T13:21:44.168Z"
}
```

`output` is a single URL string pointing to the generated JPEG image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image` or a `width` outside 512 to 2048.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/identity-preserving-art-generator-grandlineai-instant-id-artistic";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "9cad10c7870bac9d6b587f406aef28208f964454abff5c4152f7dec9b0212a9a", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

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

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

    const prediction = await response.json();

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

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

    await delay(pollInterval);
  }

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

createAndWaitForPrediction({
  "image": "https://blog.api.market/wp-content/uploads/2026/10/ip-adapter-faceid-input-api-market.png",
  "width": 640,
  "height": 640,
  "prompt": "80's anime screencap, woman wearing a denim jacket, artistic rendition with wide brush strokes, anime comic",
  "guidance_scale": 5,
  "negative_prompt": "cgi, render, bad quality, worst quality, text, signature, watermark, extra limbs, unaestheticXL_hk1, negativeXL_D",
  "ip_adapter_scale": 0.8,
  "num_inference_steps": 30,
  "controlnet_conditioning_scale": 0.8
}).then((url) => console.log(url));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/identity-preserving-art-generator-grandlineai-instant-id-artistic"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "9cad10c7870bac9d6b587f406aef28208f964454abff5c4152f7dec9b0212a9a", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-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"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

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


print(create_and_wait_for_prediction({
    "image": "https://blog.api.market/wp-content/uploads/2026/10/ip-adapter-faceid-input-api-market.png",
    "width": 640,
    "height": 640,
    "prompt": "80's anime screencap, woman wearing a denim jacket, artistic rendition with wide brush strokes, anime comic",
    "guidance_scale": 5,
    "negative_prompt": "cgi, render, bad quality, worst quality, text, signature, watermark, extra limbs, unaestheticXL_hk1, negativeXL_D",
    "ip_adapter_scale": 0.8,
    "num_inference_steps": 30,
    "controlnet_conditioning_scale": 0.8
}))
```

## FAQ
- **What kind of photo works best as `image`?**
  - A clear photo with one visible face. The model takes the identity from that face and builds the rest of the picture from the prompt.
- **How do I keep the face closer to the original?**
  - Raise `ip_adapter_scale` (up to 1) for a stronger identity match. Lower it to give the art style in the prompt more influence.
- **Do I need to send a prompt?**
  - No. If `prompt` is omitted, the default prompt describes an analog film photo of a man. In practice, describe the style you want, as in the example.
- **How many images does one request return?**
  - One JPEG image per request.
- **Can I use photos of anyone?**
  - Only use photos of people who have agreed to it, and follow the laws on likeness and privacy where you operate.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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@magicapi.com.


Turn one face photo into anime, comic or painted portraits with InstantID on Dreamshaper-XL, no fine-tuning. $0.024 per request, pay as you go.