Name: InstantID Photorealistic API: Identity-Preserving Photos
Brand: magicapi
SKU: api-magicapi-zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic
Availability: InStock
Author: API Market

Shashank Agarwal

# 👤 Identity-Preserving Portrait Generator API (grandlineai InstantID Photorealistic)

## Overview
InstantID Photorealistic generates new 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 Juggernaut-XL v8 as the base model to encourage photorealism.

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

## Features
- **Identity from one photo**: the face in `image` is carried into the generated picture.
- **Photorealistic base model**: built on Juggernaut-XL v8.
- **Prompt and negative prompt**: describe the scene 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**: place a person in cinematic, fantasy or period scenes.
2. **Profile and avatar images**: new looks and settings from a single selfie.
3. **Creative campaigns**: consistent images of the same consenting model across many scenes.

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

Prompt: "glowing, robe, fog, mist, smoke, girl composed of white light, girl composed of black smoke, fire, sun, 1girl, long hair, solo, photorealistic, cowboy shot, cinematic angle, fisheye, motion blur, blue fire, rain, Long hair fluttering in the wind, long, wave, cinematic film still"

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

### Example Output
![InstantID Photorealistic output for the example face photo and the cinematic smoke and fire prompt](https://blog.api.market/wp-content/uploads/2026/10/instant-id-photorealistic-output-54wvjdcb-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image with the face to keep |
| `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.015 per API unit.
- **1 API unit = 1 successful request with up to 13 seconds of processing.** A longer job bills one more unit for each started block of 13 seconds (for example, 35 seconds of processing is 3 units, $0.045).
- Processing time grows with `width`, `height` and `num_inference_steps`.
- **Example cost**: the example request (640 x 640, 30 steps) took 17.5 seconds of processing, which is 2 units, so $0.03.
- **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/zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic`

### 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/zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "03914a0c3326bf44383d0cd84b06822618af879229ce5d1d53bef38d93b68279",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/10/ip-adapter-faceid-input-api-market.png",
      "width": 640,
      "height": 640,
      "prompt": "glowing, robe, fog, mist, smoke, girl composed of white light, girl composed of black smoke, fire, sun, 1girl, long hair, solo, photorealistic, cowboy shot, cinematic angle, fisheye, motion blur, blue fire, rain, Long hair fluttering in the wind, long, wave, cinematic film still",
      "guidance_scale": 5,
      "ip_adapter_scale": 0.8,
      "num_inference_steps": 30,
      "controlnet_conditioning_scale": 0.6
    }
  }'
```

Response (201 Created):
```json
{
  "id": "54wvjdcb4nrmr0d1d9jvdqrv54",
  "version": "03914a0c3326bf44383d0cd84b06822618af879229ce5d1d53bef38d93b68279",
  "status": "starting",
  "created_at": "2026-10-23T20:13:22.235Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "54wvjdcb4nrmr0d1d9jvdqrv54",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/instant-id-photorealistic-output-54wvjdcb-api-market.jpg",
  "error": null,
  "created_at": "2026-10-23T20:13:22.235Z",
  "started_at": "2026-10-23T20:15:25.256Z",
  "completed_at": "2026-10-23T20:15:42.797Z"
}
```

`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
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## 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. If it fails, check that `image` shows a clearly visible face. 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/zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic";

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: "03914a0c3326bf44383d0cd84b06822618af879229ce5d1d53bef38d93b68279", 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": "glowing, robe, fog, mist, smoke, girl composed of white light, girl composed of black smoke, fire, sun, 1girl, long hair, solo, photorealistic, cowboy shot, cinematic angle, fisheye, motion blur, blue fire, rain, Long hair fluttering in the wind, long, wave, cinematic film still",
  "guidance_scale": 5,
  "ip_adapter_scale": 0.8,
  "num_inference_steps": 30,
  "controlnet_conditioning_scale": 0.6
}).then((output) => console.log(output));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/zero-shot-identity-photo-generation-grandlineai-instant-id-photorealistic"


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": "03914a0c3326bf44383d0cd84b06822618af879229ce5d1d53bef38d93b68279", "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": "glowing, robe, fog, mist, smoke, girl composed of white light, girl composed of black smoke, fire, sun, 1girl, long hair, solo, photorealistic, cowboy shot, cinematic angle, fisheye, motion blur, blue fire, rain, Long hair fluttering in the wind, long, wave, cinematic film still",
    "guidance_scale": 5,
    "ip_adapter_scale": 0.8,
    "num_inference_steps": 30,
    "controlnet_conditioning_scale": 0.6
}))
```

## 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 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 scene and style you want.
- **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, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Turn one face photo into new photorealistic scenes with InstantID on Juggernaut-XL v8: prompt-driven, identity-preserving, no fine-tuning.