Name: Faceshots – AI Headshot Generator | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-one-shot-portrait-generator-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 👤 One-Shot Portrait Generator API (Faceshots) – Instant, Lifelike Results

## Overview
The One-Shot Portrait Generator API (Faceshots) instantly transforms a single input image into a professional, lifelike portrait. Leveraging sophisticated AI techniques, this API analyzes and enhances the subject’s features, lighting, and background to produce polished, photorealistic portraits suitable for a variety of professional and creative applications.

Key highlights:
- Single-image input: No additional images or training required.  
- Quick turnaround: Receive results in seconds (depending on load).  
- High-quality outputs: Exceptional image clarity and detail.  

## Features
- • Generate a professional headshot from a single casual photo.  
- • Advanced facial recognition to maintain the subject’s identity.  
- • Automated enhancements for lighting and background to fit a professional style.  
- • Adjustable guidance scales to control the level of style/transformations.  
- • Flexible output dimensions and advanced safety controls.  

## Use Cases
1. Professional Branding for LinkedIn and Resumes  
   Instant transformation of a casual selfie into a polished professional portrait ready for LinkedIn, resumes, or corporate websites.

2. Media & Press Kits  
   Quickly generate professional portraits for media kits, press releases, and event brochures with consistent, high-quality results.

3. E-Commerce & Product Placement  
   For sellers who want a professional portrait or brand image to appear on online shops or product pages, ensuring credibility and trust.

4. Real Estate & Consulting Profiles  
   Professionals (agents, consultants) can enhance their photos for listings or promotional materials, capturing a more approachable presence.

5. Content Creators & Influencers  
   Quickly create a stunning portrait for social media profiles, channel banners, or press kits, maintaining brand consistency.

## Visual Examples

Below is an example of the input and output image provided by the API. The input is a casual photo, and the output is a refined, professional portrait.

### Input Image
![Input image: A casual photo used as source for professional portrait transformation](https://replicate.delivery/pbxt/LrKm1cmtUKTLYvEQCuB240QIhinIUcVg2vEFbkM5VN56Z7OY/pexels-creation-hill-1681010.jpg)

### Output Image
![Output image: Result of transforming the casual photo into a professional portrait](https://replicate.delivery/pbxt/TmSjI9AlKFqVI199RlircxTdg0fNCLhKKwxgJx6VPIvWUP1JA/output.jpg)

These images demonstrate how the AI can transform a simple photo into a polished and lifelike portrait suitable for professional settings.  

## Pricing
- 1 API unit = 1 image processed.  
- GET requests to check the status of a prediction are free (e.g., GET /api/v1/magicapi/one-shot-portrait-generator-api/predictions/{id}).  
- Various pricing tiers are available based on usage volume. Please refer to your dashboard or contact us for more details.

## API Documentation

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api
```

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

### Asynchronous Processing
This API uses asynchronous processing. The typical flow:
1. Submit a prediction request (POST /api/v1/magicapi/one-shot-portrait-generator-api/predictions).  
2. Receive a prediction ID in the response.  
3. Poll the GET /api/v1/magicapi/one-shot-portrait-generator-api/predictions/{id} endpoint to check status.  
4. When status becomes "succeeded," retrieve the output from the response.  

Implement a 1-second delay between polls, and a maximum timeout of 600 seconds (10 minutes).

### Endpoints

#### 1. Create a Prediction
• Endpoint:  
  POST /api/v1/magicapi/one-shot-portrait-generator-api/predictions

• Required Headers:  
  - Content-Type: application/json  
  - x-magicapi-key: YOUR_API_MARKET_KEY  

• Body Parameters (JSON):
```json
{
  "version": "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
  "input": {
    "image": "https://example.com/image.jpg",
    "width": 640,
    "height": 640,
    "prompt": "Transform this casual photo of a person img into a professional-looking portrait.",
    "guidance_scale": 0,
    "safety_checker": true,
    "negative_prompt": "",
    "ip_adapter_scale": 0.5,
    "num_inference_steps": 6,
    "controlnet_conditioning_scale": 0.5
  }
}
```

• Example cURL Request:
```bash
# Example for creating a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
    "input": {
      "image": "https://example.com/image.jpg",
      "width": 640,
      "height": 640,
      "prompt": "Transform this casual photo of a person img into a professional-looking portrait.",
      "guidance_scale": 0,
      "safety_checker": true,
      "negative_prompt": "",
      "ip_adapter_scale": 0.5,
      "num_inference_steps": 6,
      "controlnet_conditioning_scale": 0.5
    }
  }'
```

• Example Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
  "status": "starting",
  "created_at": "2025-05-21T18:15:56.294Z"
}
```

#### 2. Get Prediction Status and Result
• Endpoint:  
  GET /api/v1/magicapi/one-shot-portrait-generator-api/predictions/{id}

• Required Headers:  
  - x-magicapi-key: YOUR_API_MARKET_KEY  

• Path Parameters:
  - id (string): The unique prediction ID returned from the create prediction request.

• Example cURL Request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

• Example Response (200 OK - succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/pbxt/TmSjI9AlKFqVI199RlircxTdg0fNCLhKKwxgJx6VPIvWUP1JA/output.jpg",
  "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 successful (e.g., retrieving prediction details).  
- 201 Created: Resource successfully created (e.g., prediction creation).  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key but insufficient permissions to access the resource.  
- 404 Not Found: Specified prediction or resource could not be found.  
- 429 Too Many Requests: Exceeded the allowed rate limit or usage tier limit.  
- 500 Internal Server Error: A server-side error occurred.  
- 503 Service Unavailable: The service is temporarily unavailable.  

## Rate Limits
The API enforces rate limits depending on your plan. If you exceed your plan’s threshold, you may receive a 429 Too Many Requests response. In such cases, you should implement a backoff strategy (e.g., wait a few seconds) before retrying.

## Error Handling
When an error occurs, the API returns a JSON response with an error object describing the issue:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
Guidelines for handling errors:
- Check the error code and message to determine the cause (e.g., missing parameter, invalid API key).  
- Ensure your client code interprets these errors correctly, surfaces them to the user or logging system, and retries if appropriate.  
- For rate limit errors, implement a backoff strategy.  
- For internal server errors (5xx), retry with exponential backoff, up to a reasonable limit.

## Implementation Guide

### Example Code

#### JavaScript (Node.js) Example

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 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: "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
        input: inputData 
      })
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    const predictionId = prediction.id;
    
    // Step 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; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second
  
  const startTime = Date.now();
  
  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    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();
    
    // Check status
    if (prediction.status === "succeeded") {
      return prediction.output;
    }
    
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }
    
    // Wait before next poll
    await delay(POLL_INTERVAL);
  }
  
  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python Example

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
            "input": input_data
        }
    )
    
    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    
    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        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":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL Example

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "33bb74b80940e17f7907c9c3d42f586c674a81c32e46e92e3eb11f6629f752b5",
    "input": {
      "image": "https://example.com/image.jpg"
    }
  }'

# Response will contain a prediction ID like:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Check prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/one-shot-portrait-generator-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Keep polling this endpoint until status is "succeeded".
```

### Performance Optimization
- Keep requests as efficient as possible by using minimal inference steps for casual use.  
- Adjust the guidance scales carefully, as extreme values may increase processing time.  
- Avoid overly large image dimensions unless necessary for high-resolution outputs.

## FAQ
1. What kind of input images are best?  
   Clear, front-facing images with neutral lighting typically yield the best transformations.  

2. Can I control specific styles or backgrounds?  
   Yes, use the "prompt" field and tweak parameters (e.g., guidance_scale) for creative control.  

3. How long does it take to generate a portrait?  
   Usually within seconds, but it could take longer for high-resolution images or high server load.  

4. Is there a size limit on the input image?  
   The API supports images up to 2048×2048 pixels.  

5. What if I need more advanced or custom transformations?  
   Experiment with additional prompt text, or contact us for potential custom solutions.

## 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 lifelike AI headshots from a single photo. Get professional results in seconds. From $0.05/call. Try it free on API.market.