AI Photobook API Documentation

Overview

Produce a series of stylised portrait photos with consistent subject identity across different poses, outfits, or backgrounds.

Primary Endpoint

POST/api/v1/userPhotobook/start

Create a photobook generation task using one face image and optional location/clothing prompts. The service will generate 4, 8, 12, or 16 final photos depending on total_count. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `face_image_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userPhotobook/allRecords` — Get photobook records. - `GET /api/v1/userPhotobook/{id}` — Get photobook record detail. - `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Display name for this photobook batch
face_image_url	string	Yes	Source face image URL used for all generated photos
location	string	No	Scene or location prompt
clothing	string	No	Clothing prompt applied during the image edit step
total_count	enum: 4 \| 8 \| 12 \| 16	No	Total number of photos to generate; default: 4

Request schema and conditional rules

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Display name for this photobook batch",
      "example": "Summer Travel Album"
    },
    "face_image_url": {
      "type": "string",
      "description": "Source face image URL used for all generated photos",
      "example": "https://example.com/face.jpg"
    },
    "location": {
      "type": "string",
      "description": "Scene or location prompt",
      "example": "Paris street cafe at golden hour"
    },
    "clothing": {
      "type": "string",
      "description": "Clothing prompt applied during the image edit step",
      "example": "elegant white dress"
    },
    "total_count": {
      "type": "integer",
      "description": "Total number of photos to generate",
      "enum": [
        4,
        8,
        12,
        16
      ],
      "default": 4,
      "example": 8
    }
  },
  "required": [
    "face_image_url"
  ],
  "example": {
    "face_image_url": "https://example.com/face.jpg"
  }
}

Response Fields

code: integer
data: array<object>
data[]._id: string
data[].group_id: string
data[].batch_index: integer
data[].total_count: integer
data[].current_step: string
data[].current_status: string
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/userPhotobook/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "face_image_url": "https://example.com/face.jpg"
}'