Name: P-Video-Replace API: Person Swap in Video by Pruna AI
Brand: magicapi
SKU: api-magicapi-person-swap-video-api-prunaai-p-video-replace
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 Person Swap Video API (P-Video-Replace)

## Overview
P-Video-Replace is a model from Pruna AI that swaps the person in a video with a person from a reference image. You send a source video (the motion and audio source) and one to three identity reference images. The model returns a video in which the person from your reference image takes the place of the person in the source video, while the motion, timing, camera and scene stay as they were. Pruna AI states that generation takes about 3.58 seconds per second of video.

## Features
- **Person swap:** places the person from your reference image(s) into the source video.
- **Keeps the original shot:** motion, timing, camera and scene come from the source video.
- **One to three reference images:** pass identity reference images in `images`.
- **Placement instructions:** an optional `instruction_prompt` tells the model how to place the people from the reference images into the scene.
- **Two resolutions:** `720p` (about 1 megapixel, the default) or `1080p` (about 2 megapixels). The aspect ratio of the source video is preserved.
- **Frame rate:** keep the source frame rate (`original`, the default) or work at `24` or `48` fps with `target_fps`.
- **Audio control:** `save_audio` (default true) keeps the source audio in the output; `ignore_audio` (default false) tells the model not to use the source audio during generation.
- **Turbo mode:** `turbo` gives faster generation at slightly lower quality.

## Use Cases
- **Recasting and previews:** see how a different person would look in an existing clip without reshooting it.
- **Personalized marketing videos:** put a presenter or brand ambassador into a recorded template video.
- **Social and entertainment content:** swap a character into a dance, trend or reaction clip.
- **Training and explainer videos:** reuse one recorded performance with different on-screen people.

## Visual Examples
This is a real request sent through api.market and the file it returned.

Inputs used: `video` and `images` as shown below (all other fields at their defaults: `resolution` "720p", `target_fps` "original", `save_audio` true).

**Source video (`video`):** [Watch the source video](https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4)

**Reference image (`images`):**

![Reference image of an astronaut character used as the identity reference](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

**Output video:** [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/p-video-replace-output-api-market.mp4)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.038 per API unit.
- **1 API unit** = 1 second of output video, rounded up to the next whole second.
- **`resolution` "720p" (the default):** 1 unit per second, so $0.038 per second of output.
- **`resolution` "1080p":** 2 units per second, so $0.076 per second of output.
- **No resolution set:** the model default is `720p`, so it bills at 1 unit per second.
- **Worked example:** a 5 second output at `720p` is 5 units = $0.19. The same 5 second output at `1080p` is 10 units = $0.38. A 12 second output at `1080p` is 24 units = $0.912.
- **Failed or cancelled predictions** are not billed.
- **GET requests** to check prediction status (GET /api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace/predictions/{id}) are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
`https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace`

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

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.
1. POST `/predictions` with the model `version` and your `input`.
2. The API returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the request was accepted; it is not an error.
3. Poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
4. When `status` is `succeeded`, `output` holds the URL of the generated video.
5. When `status` is `failed`, the `error` field explains why.

### Endpoints

#### Create a Prediction
`POST /predictions`

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "bdcf16d306552a2639af54872c128020ee6e31957bb094f9be1f9e69c7442620",
    "input": {
      "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
      "images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
      ]
    }
  }'
```

Response (201 Created):
```json
{
  "id": "k7d2q9wz1hrmc0csx3vbn4tpfa",
  "version": "bdcf16d306552a2639af54872c128020ee6e31957bb094f9be1f9e69c7442620",
  "status": "starting",
  "created_at": "2026-10-13T10:58:12.341Z"
}
```

#### Check Prediction Status
`GET /predictions/{id}`

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace/predictions/k7d2q9wz1hrmc0csx3vbn4tpfa" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response (200 OK) once the prediction has finished:
```json
{
  "id": "k7d2q9wz1hrmc0csx3vbn4tpfa",
  "status": "succeeded",
  "input": {
    "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
    "images": [
      "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
    ]
  },
  "output": "https://blog.api.market/wp-content/uploads/2026/10/p-video-replace-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-13T10:58:12.341Z",
  "started_at": "2026-10-13T10:58:12.902Z",
  "completed_at": "2026-10-13T10:58:41.517Z"
}
```

### Input Parameters
| Parameter | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `video` | string (URL) | Yes | none |  | Source RGB video (.mp4): motion + audio source. |
| `images` | array of URLs | Yes | none |  | Identity reference image(s) (1-3) to place into the video. |
| `instruction_prompt` | string | No | "" (empty) |  | Further instruction on how to place the people from the reference images into the scene. |
| `resolution` | string | No | "720p" | `720p`, `1080p` | Target ~megapixel budget: 720p ≈ 1 MP, 1080p ≈ 2 MP (aspect ratio preserved). |
| `target_fps` | string | No | "original" | `original`, `24`, `48` | Target FPS for the working video. |
| `save_audio` | boolean | No | true |  | Save the video with audio. |
| `ignore_audio` | boolean | No | false |  | Ignore source audio during generation. If save_audio is true, the source audio is still saved with the final video. |
| `turbo` | boolean | No | false |  | Turbo mode: faster generation for slightly lower quality. |
| `disable_safety_checker` | boolean | No | false |  | Disable safety checker for generated videos. |
| `seed` | integer | No | none |  | Random seed. Leave blank for random. |
| `no_op` | boolean | No | false |  | Defined by the model without a description. Leave it at the default (false). |

### Output
`output` is a single URL (string) pointing to the generated MP4 video.

## Status Codes
- **200 OK:** prediction status returned.
- **201 Created:** prediction accepted. Poll GET `/predictions/{id}` for the result.
- **400 Bad Request:** invalid or missing input fields.
- **401 Unauthorized:** missing or invalid API key.
- **404 Not Found:** unknown prediction ID.
- **429 Too Many Requests:** too many requests in a short time. Wait and retry.
- **500 Internal Server Error:** server-side error. Retry after a short wait.

## 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
- **Request errors (4xx):** check the response body, fix the input fields and send the request again.
- **Failed predictions:** when GET returns `status: "failed"`, read the `error` field. Failed predictions are not billed.
- **Rate limits (429) and server errors (5xx):** retry with exponential backoff.

## Implementation Guide

### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace";

async function createPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "bdcf16d306552a2639af54872c128020ee6e31957bb094f9be1f9e69c7442620", input })
  });
  if (response.status !== 201 && response.status !== 200) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }
  return response.json();
}

async function waitForPrediction(id, timeoutMs = 1200000, intervalMs = 5000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const response = await fetch(`${baseUrl}/predictions/${id}`, {
      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 new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  throw new Error("Timed out waiting for the prediction");
}

const prediction = await createPrediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "images": [
    "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
  ]
});
const output = await waitForPrediction(prediction.id);
console.log(output);
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace"

def create_prediction(input_data):
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers={"Content-Type": "application/json", "x-api-market-key": API_KEY},
        json={"version": "bdcf16d306552a2639af54872c128020ee6e31957bb094f9be1f9e69c7442620", "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    return response.json()

def wait_for_prediction(prediction_id, timeout=1200, interval=5):
    start = time.time()
    while time.time() - start < timeout:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-key": API_KEY},
        )
        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(interval)
    raise Exception("Timed out waiting for the prediction")

prediction = create_prediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "images": [
    "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
  ]
})
print(wait_for_prediction(prediction["id"]))
```

### cURL
```bash
# Step 1: create the prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "bdcf16d306552a2639af54872c128020ee6e31957bb094f9be1f9e69c7442620",
    "input": {
      "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
      "images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
      ]
    }
  }'

# Step 2: poll with the returned id until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/person-swap-video-api-prunaai-p-video-replace/predictions/k7d2q9wz1hrmc0csx3vbn4tpfa" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## FAQ
**Q: How many reference images can I send?**  
A: One to three, in the `images` array.

**Q: How long is the output video?**  
A: The motion and timing come from your source video, and you are billed for the seconds of video the model returns.

**Q: What does `ignore_audio` do?**  
A: It tells the model not to use the source audio during generation. If `save_audio` is true, the source audio is still saved with the final video.

**Q: What is the difference between 720p and 1080p?**  
A: `720p` targets about 1 megapixel per frame and costs 1 unit per second. `1080p` targets about 2 megapixels per frame and costs 2 units per second. Both keep the source aspect ratio.

**Q: Is POST returning 201 an error?**  
A: No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## 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.


Replace the person in a video with one from a reference image using Pruna AI P-Video-Replace. Billed per second of output, from $0.038 per second at 720p.