> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gostudio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Photo

> Swap faces from multiple input images into a reference group scene.

The Group Photo API inserts people from your input images into a reference scene. You provide 2–20 face images and a target background scene, and the API returns a composed group photo with those faces placed naturally into the scene.

The call is **synchronous** — one request, one finished result.

> [!WARNING]
>
> The API holds the connection until the job completes. This can take up to **four minutes**. Most HTTP clients default to a 30-second timeout — raise yours to at least 300 seconds.

## Before you start

* A valid **Bearer token**. See [Authentication](https://docs.gostudio.ai/authentication.md).
* Enough **credits**. Failed generations are refunded automatically.
* **Publicly reachable image URLs** — all input and reference images are fetched server-side and cannot require authentication or have expired signed URLs.

## Step 1 — Submit the request

```bash curl theme={null}
curl -X POST https://www.gostudio.ai/api/v2/image/group-photo \
  --max-time 300 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input_image_urls": [
      "https://example.com/person1.jpg",
      "https://example.com/person2.jpg"
    ],
    "reference_image_url": "https://example.com/office-scene.jpg",
    "genders": ["male", "female"],
    "aspect_ratio": "16:9"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://www.gostudio.ai/api/v2/image/group-photo", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input_image_urls: [
      "https://example.com/person1.jpg",
      "https://example.com/person2.jpg"
    ],
    reference_image_url: "https://example.com/office-scene.jpg",
    genders: ["male", "female"],
    aspect_ratio: "16:9"
  }),
  signal: AbortSignal.timeout(300_000)
});

const { data } = await res.json();
console.log(data.output_urls[0]);
```

```python Python theme={null}
import httpx

r = httpx.post(
    "https://www.gostudio.ai/api/v2/image/group-photo",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "input_image_urls": [
            "https://example.com/person1.jpg",
            "https://example.com/person2.jpg",
        ],
        "reference_image_url": "https://example.com/office-scene.jpg",
        "genders": ["male", "female"],
        "aspect_ratio": "16:9",
    },
    timeout=300.0,
)

print(r.json()["data"]["output_urls"][0])
```

### Request fields

| Field | Type | Required | Description |
| - | - | - | - |
| `input_image_urls` | string\[] | Yes | 2–20 HTTPS URLs of source face images. |
| `reference_image_url` | string | Yes | HTTPS URL of the target scene or background. |
| `genders` | string\[] | No | Gender hint per input image, in the same order: `"male"`, `"female"`, `"pets"`, `"others"`. Helps placement accuracy. |
| `instructions` | string | No | Extra guidance for the scene composition. |
| `prompt` | string | No | Override the auto-generated scene prompt entirely. |
| `num_output_images` | integer | No | Number of images to generate. Default `1`, max `4`. |
| `aspect_ratio` | string | No | `"auto"`, `"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"`. Auto-detected from the reference image if omitted. |
| `resolution` | string | No | `"low"` (default), `"medium"`, `"high"`. |
| `output_format` | string | No | `"png"` (default) or `"jpg"`. |

> [!NOTE]
>
> The scene prompt is generated automatically from the reference image. Use `instructions` to refine it, or `prompt` to replace it entirely.

## Step 2 — Read the response

```json theme={null}
{
  "status": 200,
  "data": {
    "kind": "generation",
    "job_id": "enc_jkl012",
    "credits_deducted": 15,
    "credit_balance": 485,
    "created_at": "2026-10-03T10:00:00Z",
    "output_urls": ["https://cdn.gostudio.ai/output/jkl.png"]
  }
}
```

| Field | Type | Description |
| - | - | - |
| `job_id` | string | Encoded job ID. Keep it to re-fetch results with [Job Status](https://docs.gostudio.ai/guides/job-status.md). |
| `output_urls` | string\[] | CDN URLs for the generated images, ready to use immediately. |
| `credits_deducted` | integer | Credits consumed by this request. |
| `credit_balance` | integer | Your remaining balance afterwards. |

Credits are reserved when the job is accepted and **refunded automatically** if the generation fails.

## Common issues

| Symptom | Likely cause | Fix |
| - | - | - |
| Client timeout, no response | Default HTTP timeout too short | Raise it to 300s. Look up the result with [Job Status](https://docs.gostudio.ai/guides/job-status.md). |
| `400 invalid_input` | Fewer than 2 input images, or invalid URL | Provide at least 2 valid HTTPS URLs in `input_image_urls`. |
| `401 unauthorized` | Token expired | Fetch a fresh token — see [Authentication](https://docs.gostudio.ai/authentication.md). |
| `402 insufficient_credits` | Balance too low | Purchase credits in your GoStudio account. |
| `429 rate_limited` | Too many requests | Back off and retry. |
| `502 external_service_failed` | Vision model or provider failure | Retry the request. |

See [Errors](https://docs.gostudio.ai/errors.md) for the full code reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.