> ## 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. # Swap faces into a group scene > Inserts 2–20 people from input images into a reference group scene. The scene prompt is auto-generated from the reference image; an optional `prompt` field overrides it entirely. The call blocks until generation completes. Credits are deducted before generation begins and refunded if the job fails. ## OpenAPI ````yaml /openapi.yaml post /api/v2/image/group-photo openapi: 3.0.3 info: title: GoStudio API version: 2.0.0 description: > The GoStudio v2 REST API. Every response uses a standard envelope: successes return `{ status, data }`; errors return `{ status, error: { type, code, message } }`. All endpoints require a **Bearer token** in the `Authorization` header. The one exception is the provider webhook callback, which is authenticated by signature. servers: - url: https://www.gostudio.ai description: Production security: - bearerAuth: [] tags: - name: Watermark Remover description: AI watermark removal — orchestration, model metadata, and job polling. - name: Photo description: >- AI photo generation — generate, recreate, and manage trained profile photos. - name: Image description: Image utilities — group photo composition and image-to-prompt analysis. - name: Media description: Media upload and CDN management. - name: Apps description: GoStudio application tools — age modifier and other transformations. - name: Job Status description: Generic job polling — works across all GoStudio tools. - name: Webhooks description: Endpoints called by external services, not by your application. paths: /api/v2/image/group-photo: post: tags: - Image summary: Swap faces into a group scene description: > Inserts 2–20 people from input images into a reference group scene. The scene prompt is auto-generated from the reference image; an optional `prompt` field overrides it entirely. The call blocks until generation completes. Credits are deducted before generation begins and refunded if the job fails. operationId: createGroupPhoto requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupPhotoRequest' examples: basic: summary: Two-person group swap value: 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' responses: '200': description: Group photo generated successfully. content: application/json: schema: type: object properties: status: type: integer example: 200 data: $ref: '#/components/schemas/GenerationResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' components: schemas: GroupPhotoRequest: type: object required: - input_image_urls - reference_image_url properties: input_image_urls: type: array description: HTTPS URLs of the source face images. 2–20 items. items: type: string format: uri minItems: 2 maxItems: 20 example: - https://example.com/person1.jpg - https://example.com/person2.jpg reference_image_url: type: string format: uri description: HTTPS URL of the target scene or background image. example: https://example.com/office-scene.jpg genders: type: array description: Gender hint per input image, in order. items: type: string enum: - male - female - pets - others example: - male - female instructions: type: string description: Additional instructions for the scene composition. prompt: type: string description: Override the auto-generated scene prompt. num_output_images: type: integer description: Number of output images. default: 1 minimum: 1 maximum: 4 aspect_ratio: type: string description: >- Output aspect ratio. Auto-detected from the reference image if omitted. enum: - auto - '1:1' - '3:4' - '4:3' - '9:16' - '16:9' resolution: type: string description: Output resolution. enum: - low - medium - high default: low output_format: type: string description: Output image format. enum: - png - jpg default: png GenerationResult: type: object properties: kind: type: string description: Always "generation". example: generation job_id: type: string description: > Encoded job identifier. Use with `GET /api/v2/apps/job/{job_id}` to poll status or re-fetch results. example: enc_abc123 credits_deducted: type: integer description: Credits spent on this generation. example: 10 credit_balance: type: integer description: Remaining credit balance after this request. example: 490 created_at: type: string format: date-time description: ISO 8601 timestamp when the job was created. output_urls: type: array description: CDN URLs for the generated images. items: type: string format: uri ErrorResponse: type: object properties: status: type: integer example: 400 error: type: object properties: type: type: string example: validation_error code: type: string example: invalid_input dev: type: integer example: 40001 message: type: string example: Some information is invalid. responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 400 error: type: validation_error code: invalid_input dev: 40001 message: Some information is invalid. Unauthorized: description: Missing or invalid Authorization Bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 401 error: type: authentication_error code: unauthorized dev: 40100 message: Missing or invalid Authorization Bearer token. PaymentRequired: description: The account does not have enough credits for this request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 402 error: type: billing_error code: insufficient_credits dev: 40200 message: You don't have enough credits. Forbidden: description: Caller type not allowed for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 403 error: type: permission_error code: forbidden dev: 40300 message: You don't have permission for this action. RateLimited: description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 429 error: type: rate_limit_error code: rate_limited dev: 42900 message: You're doing that too often. Please wait a moment. ServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 500 error: type: system_error code: internal_error dev: 50000 message: Something went wrong on our end. BadGateway: description: > The upstream model provider rejected the submission, was unreachable, or returned an unusable response while the job was being submitted or checked. The generation is marked failed and the credits reserved for it are refunded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 502 error: type: provider_error code: provider_bad_gateway dev: 50200 message: Generation is having trouble right now. Please try again. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Supabase user JWT (or an internal service token). Send as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.