---
title: "Create a shape collage (heart, number, word ...) from photos"
method: POST
path: "/collages"
tags: ["collages"]
---

# Create a shape collage (heart, number, word ...) from photos

`POST /collages`

## Request

- Base URL: `https://api.collager.ai/v1`
- URL: `https://api.collager.ai/v1/collages`
- Auth: HTTP bearer

## Headers

- `Prefer` string
- `Idempotency-Key` string

## Request body

- CreateCollageRequest
  - `shape` Shape, required: Examples: {"type":"heart"}, {"type":"heart","cells":70}, {"type":"number","text":"30"}, {"type":"text","text":"LOVE"}, {"type":"love"}, {"type":"star","size":"large"}, {"type":"grid","n":4}, {"type":"mask_url","url":"https://..."}. GET /shapes lists them.
    - `type` 'heart' | 'number' | 'text' | 'love' | 'circle' | 'star' | 'flower' | 'daisy' | 'yinyang' | 'grid' | 'mask_url', required
    - `cells` 27 | 34 | 70 | 79 | 91 | 164: Heart only. Omitted - the smallest heart that holds all your photos.
    - `text` string
    - `size` 'small' | 'medium' | 'large'
    - `n` integer
    - `url` string, uri: mask_url - black-and-white picture, each black pixel is one photo cell.
  - `photo_urls` string[], required: Photos (JPEG/PNG/WEBP). Fewer photos than cells - photos repeat.
  - `gap_pct` number
  - `size_px` integer: Long side of the full-resolution file (the figure keeps a 9 % white margin).
  - `background` string: white, cream, pink, gray, black or
  - `webhook_url` string, uri
  - `metadata` object

## Response `200`

Finished within the Prefer wait time.

- Collage
  - `id` string, required
  - `object` 'collage', required
  - `status` 'queued' | 'processing' | 'preview_ready' | 'unlocked' | 'failed', required
  - `shape` string, nullable
  - `cells` integer, nullable
  - `photos_used` integer, nullable
  - `width` integer, nullable
  - `height` integer, nullable
  - `preview_url` string, uri, nullable: Watermarked preview (<= 1200 px). Link valid 24 h - every GET gives a fresh one.
  - `hd_url` string, uri, nullable: Clean full-resolution JPEG, after unlock. Link valid 24 h.
  - `credits_left` integer: Returned by unlock.
  - `credits_charged` integer: Returned by unlock - 1 the first time, 0 on repeats.
  - `error` JobError
    - `code` string, required
    - `message` string, required
  - `metadata` object
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, required

## Other responses

- `202`: Accepted; poll GET /collages/{id}.
- `400`: Error.
- `401`: Error.
- `429`: Error.

---

[API](https://skmtc.dev/collager/apis/collager-ai-photo-mosaic-photo-collage-api.md) · [All operations](https://skmtc.dev/collager/apis/collager-ai-photo-mosaic-photo-collage-api/llms.txt) · [OpenAPI document](https://skmtc.dev/collager/apis/collager-ai-photo-mosaic-photo-collage-api/revisions/719c6e7aaf09?raw)