Group Photo - GoStudio API

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.

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

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"
  }'

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]);

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"`.

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

{
  "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.
`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.
`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.
`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 for the full code reference.