Name: Flux Kontext – AI Headshot Generator | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-professional-headshot-generator-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 👔 Professional Headshot Generator API (Flux-Kontext)

## Overview
The Professional Headshot Generator API by Flux-Kontext instantly turns any single image into a polished, high-quality professional headshot. This is ideal for LinkedIn, resumes, corporate profiles, and business branding. It supports various customization options such as background choice, aspect ratio, and gender specification to ensure the best suited professional look for different needs.

![Example input image used to generate a professional headshot](https://blog.api.market/wp-content/uploads/2025/07/apI_market_imagen_4.jpg)
![Example output image generated by the API](https://blog.api.market/wp-content/uploads/2026/01/professional-api-market.png)

## Features
- Transform any single image into a polished headshot with a single API call.  
- Select from various backgrounds (white, black, neutral, gray, office) to suit different professional contexts.  
- Set a custom aspect ratio or match the input image's ratio.  
- Choose output file format (JPEG or PNG).  
- Specify an optional random seed for reproducible results.  
- Optimized safety filtering to ensure professional, appropriate outputs.  

## Use Cases
1. HR & Recruitment: Upload job applicants’ or employees’ photos to standardize professional headshots for internal directories or LinkedIn profiles.  
2. Corporate Branding: Quickly generate uniform, on-brand headshots for employees’ email signatures, company websites, and marketing materials.  
3. Freelancers & Consultants: Improve personal branding on platforms like Upwork or Fiverr by displaying a polished headshot that matches your niche.  
4. Real Estate Agents & Brokers: Maintain a consistent look across agencies’ websites and property listings with professional agent headshots.  
5. Influencers & Content Creators: Create consistent profile pictures for social media and brand collaborations, tailored to specific backgrounds or aspect ratios.  


## Pricing
- Pay As You Go (PAYG) pricing — only pay for the images you process.  
- 1 API unit = 1 image processed.  
- All GET requests to check prediction status (GET /api/v1/magicapi/professional-headshot-generator-api/predictions/{id}) are free and do not consume API units.  
- No monthly subscription fees or usage limits — simple per-call pricing structure.

## API Documentation

### Base URL
All requests should be directed to:  
```
https://prod.api.market/api/v1/magicapi/professional-headshot-generator-api
```

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

### Asynchronous Processing
This API processes headshot transformations asynchronously. The typical workflow is:

1. POST your prediction request (with images and parameters).  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint (using the prediction ID) to check the status.  
4. When the status is “succeeded,” retrieve the generated headshot from the response.  

Your client should:
- Wait at least 1 second (polling interval) between repeated GET requests.  
- Implement a maximum overall timeout of 10 minutes (600 seconds).  
- Stop polling when the status is “failed” (handle the error) or “succeeded” (retrieve the image).  

### Endpoints

#### 1. Create a Prediction
• Path:  
  POST /api/v1/magicapi/professional-headshot-generator-api/predictions  

• Description:  
  Creates a new headshot generation task.  

• Sample Request (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/professional-headshot-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "9528356a9ef5338a02a0e7902d18de1c70caff262954ee37ab31bf8ce1e2c905",
    "input": {
      "gender": "female",
      "background": "neutral",
      "input_image": "https://blog.api.market/wp-content/uploads/2026/01/input-api-market.png",
      "aspect_ratio": "1:1"
    }
  }'
```

• Sample Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "9528356a9ef5338a02a0e7902d18de1c70caff262954ee37ab31bf8ce1e2c905",
  "status": "starting",
  "created_at": "2025-07-11T07:33:34.851Z"
}
```
  
#### 2. Get Prediction Status & Result
• Path:  
  GET /api/v1/magicapi/professional-headshot-generator-api/predictions/{id}

• Description:  
  Checks the current status of a prediction and, once completed, provides the output URL.

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

• Sample Response (JSON where status is “succeeded”):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/01/professional-api-market.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 succeeded.
- 201 Created: Resource (prediction) created successfully.
- 400 Bad Request: Invalid or malformed input data.
- 401 Unauthorized: Missing or invalid API key in headers.
- 403 Forbidden: The provided API key does not have permission.
- 404 Not Found: The specified resource or prediction does not exist.
- 429 Too Many Requests: Rate limit has been reached or exceeded.
- 500 Internal Server Error: A server-side error occurred.
- 503 Service Unavailable: The service is temporarily unavailable; try again later.

## Rate Limits
Details about rate limits (if applicable to your plan or usage tier) may vary, but generally:
- Requests above the defined threshold may result in a 429 response.  
- Implement backoff logic or slower polling if encountering rate limits.

## Error Handling
When the API responds with an error status code (e.g., 400, 401, 500), it will typically return a JSON payload describing the issue:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'input_image' is required",
    "status": 400
  }
}
```
Best practices:
- Check the “message” field for clues about which parameters are missing or invalid.  
- Retry only if the error is transient (like a 503 or 429).  
- For parameter or authentication errors, fix the input or credentials and retry accordingly.

## Implementation Guide

### Example Code

#### JavaScript (Node.js)
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/professional-headshot-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: "9528356a9ef5338a02a0e7902d18de1c70caff262954ee37ab31bf8ce1e2c905",
        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-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({
//   gender: "female",
//   background: "neutral",
//   input_image: "https://example.com/your-image.jpg",
//   aspect_ratio: "1:1"
// })
//   .then(outputUrl => console.log("Professional headshot URL:", outputUrl))
//   .catch(err => console.error("Error:", err));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/professional-headshot-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
    }
    payload = {
        "version": "9528356a9ef5338a02a0e7902d18de1c70caff262954ee37ab31bf8ce1e2c905",
        "input": input_data
    }
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)

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

        time.sleep(POLL_INTERVAL)

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

# Example usage:
# output_url = create_and_wait_for_prediction({
#     "gender": "female",
#     "background": "neutral",
#     "input_image": "https://example.com/your-image.jpg",
#     "aspect_ratio": "1:1"
# })
# print("Professional headshot URL:", output_url)
```

#### cURL
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/professional-headshot-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "9528356a9ef5338a02a0e7902d18de1c70caff262954ee37ab31bf8ce1e2c905",
    "input": {
      "input_image": "https://example.com/your-image.jpg",
      "aspect_ratio": "1:1"
    }
  }'

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

# Step 2: Check the status of the prediction (poll repeatedly until status is succeeded or failed)
curl -X GET "https://prod.api.market/api/v1/magicapi/professional-headshot-generator-api/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Only create predictions for images that genuinely need professional conversion to reduce costs.  
- Poll no faster than once per second to avoid rate-limiting.  
- Use a timeout to avoid hanging indefinitely.  

## FAQ
1. How long does it take to generate a headshot?  
   - It typically completes within a few seconds, but large images or high server load can extend this up to a couple of minutes.  

2. Can the API handle multiple concurrent requests?  
   - Yes. However, be mindful of rate limits and set up suitable polling intervals.  

3. Can I specify a custom background?  
   - The API offers preset background options. If you need more options, contact us with your feature requests.  

4. Do I pay even if the request fails?  
   - In most cases, unsuccessful attempts still incur usage since they consume resources. However, check the exact policy in your billing details.  

5. How can I reproduce the exact same result?  
   - Use the “seed” parameter in your inputs to ensure the same random seed is applied.

## 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 professional, studio-quality headshots from any single photo. Customize backgrounds, lighting, and attire. From $0.05/call. Try it free on API.market.

Flux Kontext – AI Headshot Generator | $0.05/call | API.market

👔 Professional Headshot Generator API (Flux-Kontext)

PAYG

MagicAPI

Instantly transform any image into a polished, high-quality professional headshot—ideal for profiles, resumes, and business branding, powered by Flux-Kontext.