Name: Portrait Series Multi-Pose Portrait Generator API
Brand: magicapi
SKU: api-magicapi-portrait-photo-series-generator-flux-kontext-apps-portrait-series
Availability: InStock
Author: API Market

Shashank Agarwal

# 📸 Portrait Series Generator API - Many Poses from One Photo (FLUX Kontext)

## Overview
Portrait Series is a FLUX Kontext app that creates a series of portrait photos from a single image of a person. Each image in the series shows the person in a different pose.

Send the photo as `input_image`, choose how many poses you want with `num_images` (1 to 13, default 4) and pick a `background`. Each request returns a list of image URLs, one per pose.

## Features
- **Several poses from one photo**: `num_images` sets how many poses to generate, from 1 to 13 (default 4).
- **Backgrounds**: `white` (default), `black`, `gray`, `green screen`, `neutral`, or `original` to keep the background of your photo.
- **Randomized poses**: set `randomize_images` to `true` to randomize the poses (default `false`).
- **Output format**: `png` (default) or `jpg`.
- **Safety tolerance**: `safety_tolerance` from 0 (most strict) to 2 (most permissive, the default and the maximum allowed).

## Use Cases
1. **Profile photo sets**: get several portrait options from one photo for team pages, speaker bios or social profiles.
2. **Consistent team pages**: run each person's photo with the same `background` so every portrait in the set matches.
3. **Green screen portraits**: choose `green screen` to place the person on a background of your own later.
4. **Pose references**: build a set of poses of the same person for design mockups or storyboards.

## Visual Examples
### Example Input
Input image:

![Example input: a portrait photo of a person](https://blog.api.market/wp-content/uploads/2026/10/p-video-avatar-input-api-market.webp)

- **num_images**: `4`
- **background**: `neutral`

All other fields were left at their defaults (`randomize_images` `false`, `output_format` `png`, `safety_tolerance` `2`).

### Example Output
![Portrait series output 1 of 4: the person from the input photo in a new pose on a neutral background](https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-1-api-market.jpg)

![Portrait series output 2 of 4: the person from the input photo in a new pose on a neutral background](https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-2-api-market.jpg)

![Portrait series output 3 of 4: the person from the input photo in a new pose on a neutral background](https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-3-api-market.jpg)

![Portrait series output 4 of 4: the person from the input photo in a new pose on a neutral background](https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-4-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `input_image` | string (URL) | Yes |  |  | Image of the person to create a series of photos for. Image URL (jpeg, png, gif or webp). |
| `num_images` | integer | No | `4` | 1 to 13 | The number of poses to generate. Each pose is one output image. |
| `background` | string | No | `white` | `white`, `black`, `gray`, `green screen`, `neutral`, `original` | The background of the photos. `original` keeps the background of the input image. |
| `randomize_images` | boolean | No | `false` |  | Whether to randomize the poses. |
| `output_format` | string | No | `png` | `jpg`, `png` | Output format for the generated images. |
| `safety_tolerance` | integer | No | `2` | 0 to 2 | Safety tolerance, 0 is most strict and 2 is most permissive. 2 is currently the maximum allowed. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.05 per API unit.
- **1 API unit = 1 output image.** A request returns `num_images` images (1 to 13, default 4), so a request costs `num_images` x $0.05.
- **Worked examples**: the default 4 poses cost $0.20; 1 pose costs $0.05; the maximum of 13 poses costs $0.65.
- Background, randomized poses, output format and safety tolerance do not change the price. **The example request above** returned 4 images and cost $0.20.
- **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/portrait-photo-series-generator-flux-kontext-apps-portrait-series`

### 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/portrait-photo-series-generator-flux-kontext-apps-portrait-series/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "82608cda7abb9252da1ef78e38cc3730d2f8714cf52c92c5767a120d40d3e6c5",
    "input": {
      "input_image": "https://blog.api.market/wp-content/uploads/2026/10/p-video-avatar-input-api-market.webp",
      "num_images": 4,
      "background": "neutral"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "pmkdydkpk5rmy0d17framjhr30",
  "version": "82608cda7abb9252da1ef78e38cc3730d2f8714cf52c92c5767a120d40d3e6c5",
  "status": "starting",
  "created_at": "2026-10-14T19:42:57.313Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/portrait-photo-series-generator-flux-kontext-apps-portrait-series/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "pmkdydkpk5rmy0d17framjhr30",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-1-api-market.jpg",
    "https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-2-api-market.jpg",
    "https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-3-api-market.jpg",
    "https://blog.api.market/wp-content/uploads/2026/10/portrait-series-output-4-api-market.jpg"
  ],
  "error": null,
  "created_at": "2026-10-14T19:42:57.313Z",
  "started_at": "2026-10-14T19:42:58.313Z",
  "completed_at": "2026-10-14T19:43:37.313Z"
}
```

`output` is a list of image URLs, one per pose, in order. Its length equals `num_images`.

### 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 `input_image`, a `num_images` outside 1 to 13, or a `background` that is not in the list.
- **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. 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/portrait-photo-series-generator-flux-kontext-apps-portrait-series";

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: "82608cda7abb9252da1ef78e38cc3730d2f8714cf52c92c5767a120d40d3e6c5", 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({
  "input_image": "https://blog.api.market/wp-content/uploads/2026/10/p-video-avatar-input-api-market.webp",
  "num_images": 4,
  "background": "neutral"
}).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/portrait-photo-series-generator-flux-kontext-apps-portrait-series"

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": "82608cda7abb9252da1ef78e38cc3730d2f8714cf52c92c5767a120d40d3e6c5", "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({
  "input_image": "https://blog.api.market/wp-content/uploads/2026/10/p-video-avatar-input-api-market.webp",
  "num_images": 4,
  "background": "neutral"
}))
```

## FAQ
- **How many images does one request return?**
  - As many as `num_images`, from 1 to 13 (default 4). Each image is billed as one API unit ($0.05), so the default request costs $0.20.
- **Can I keep the background of my photo?**
  - Yes. Set `background` to `original`. The other options replace it with `white`, `black`, `gray`, `green screen` or `neutral`.
- **Which image formats can I send?**
  - Send `input_image` as a URL to a jpeg, png, gif or webp image of the person.
- **Does `randomize_images` change the price?**
  - No. The price depends only on the number of images returned.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **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.


Create 1 to 13 portrait photos of a person in different poses from a single image, on a plain, green screen or original background. $0.05 per image.