Hundreds of photos in, one portrait out.

What you get

The same engine has built mosaics for Collager.ai customers, print shops and events. One main photo plus a few hundred personal photos make one picture.

→

Want to see the photos fly into place? Watch the photo mosaic assembly video — we can render one for any mosaic.

How it works

Assembly takes minutes, not milliseconds, so the API is asynchronous: create a job, then poll it or wait for a webhook.

1. POST /v1/mosaics

   Send the main photo and the tile photos — as a list of URLs, one ZIP, a folder in your cloud bucket, a file upload, or an upload link for your own users (six ways). Optionally a webhook_url. You get back a job id straight away.

2. GET /v1/mosaics/{id}

   Check the status: queued → processing → preview_ready (or failed with a reason).

3. Watermarked preview

   When the status is preview_ready, the response carries preview_url — a watermarked image you can show to your user for approval.

4. POST /v1/mosaics/{id}/unlock

   Spend credits from your Collager.ai balance to unlock the mosaic. The response carries hd_url — the clean full-resolution file.

5. Webhook (optional)

   If you passed webhook_url, we POST the job object to it when the preview is ready or the job fails — no polling needed.

Examples

Authentication is a bearer key: Authorization: Bearer <your key>. Base URL: https://api.collager.ai/v1 (planned).

# 1. Create a mosaic job
curl -X POST https://api.collager.ai/v1/mosaics \
  -H "Authorization: Bearer $COLLAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "main_image_url": "https://example.com/portrait.jpg",
    "tile_image_urls": ["https://example.com/p/001.jpg", "https://example.com/p/002.jpg"],
    "webhook_url": "https://example.com/hooks/collager"
  }'
# → 202 {"id": "msc_7Hq2...", "status": "queued"}

# 2. Poll the status
curl https://api.collager.ai/v1/mosaics/msc_7Hq2... -H "Authorization: Bearer $COLLAGER_API_KEY"
# → {"id": "msc_7Hq2...", "status": "preview_ready", "preview_url": "https://..."}

# 3. Unlock the HD file for credits
curl -X POST https://api.collager.ai/v1/mosaics/msc_7Hq2.../unlock -H "Authorization: Bearer $COLLAGER_API_KEY"
# → {"id": "msc_7Hq2...", "status": "unlocked", "hd_url": "https://...", "credits_left": 41}

import os, time, requests

API = "https://api.collager.ai/v1"
H = {"Authorization": f"Bearer {os.environ['COLLAGER_API_KEY']}"}

job = requests.post(f"{API}/mosaics", headers=H, json={
    "main_image_url": "https://example.com/portrait.jpg",
    "tile_image_urls": [f"https://example.com/p/{i:03}.jpg" for i in range(1, 301)],
}).json()

while job["status"] in ("queued", "processing"):
    time.sleep(20)                      # assembly takes minutes
    job = requests.get(f"{API}/mosaics/{job['id']}", headers=H).json()

if job["status"] == "preview_ready":
    print("Preview:", job["preview_url"])   # watermarked
    hd = requests.post(f"{API}/mosaics/{job['id']}/unlock", headers=H).json()
    print("HD file:", hd["hd_url"])

POST https://example.com/hooks/collager
{
  "event": "mosaic.preview_ready",
  "mosaic": {
    "id": "msc_7Hq2...",
    "status": "preview_ready",
    "preview_url": "https://...",
    "tiles_used": 300,
    "created_at": "2026-10-14T12:00:00Z"
  }
}
# Other events: mosaic.unlocked, mosaic.failed. Each delivery is signed with an X-Collager-Signature header.

Endpoints

The full draft is in openapi.yaml (OpenAPI 3.1, marked x-status: early-access).

API reference

The details an integration needs. Everything here is the planned v1 behaviour — the same contract as in openapi.yaml.

Authentication and keys

Create a mosaic — request fields

One way of passing the tiles per job — pick whichever fits your system (next section). Send an Idempotency-Key header with every POST: a retried request with the same key returns the same job instead of creating a second one.

How to send the photos

A mosaic needs one main photo and many tile photos. Send them the way your photos already live — we adapt to you, not the other way round.

The main photo comes as main_image_url or as the main_image file. JPEG and PNG work everywhere; tell us if you need HEIC or RAW.

Job statuses

File links (preview_url, hd_url) are time-limited. Download the file or call GET /v1/mosaics/{id} again for a fresh link.

# GET /v1/mosaics/msc_7Hq2xV9 → 200
{
  "id": "msc_7Hq2xV9",
  "status": "preview_ready",
  "preview_url": "https://…/preview.jpg",
  "hd_url": null,
  "tiles_used": 300,
  "error": null,
  "metadata": {"order_id": "A-1042"},
  "created_at": "2026-10-14T12:00:00Z"
}

Errors

Errors come as JSON: {"error": "insufficient_credits", "message": "…"}.

Limits

Assembly runs on our own render farm, so each key has a limit on jobs running at the same time and on requests per minute. Limits are set per key and returned by GET /v1/account; for higher volume, write to us.

Webhooks

We POST a JSON event (mosaic.preview_ready, mosaic.unlocked, mosaic.failed) to your webhook_url. Each delivery has an X-Collager-Signature header: HMAC-SHA256 of the raw body with your webhook secret — check it before trusting the event. Answer 2xx within 10 seconds; otherwise we retry with growing pauses for up to 24 hours. Events can arrive twice — use the job id to ignore duplicates.

Keys and credits

High volume, white-label or your own watermark: write to us — volume terms are set by agreement.

For AI agents and tools

Building an assistant, an agent or a no-code automation? These are the machine-readable entry points.