A REST API that builds a photo mosaic from a set of photos: you send one main photo and the photos for the tiles, we assemble a mosaic where every tile is one of those photos. You get a watermarked preview first and unlock the HD file for credits.
https://collager.ai/mcp without a key.A real mosaic from our engine: a family portrait made of thousands of stock photos. The same mosaic is shown in the zoom and style examples below. Download it in 4K.
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.

main_image_url — the picture to recreate
tile_image_urlsZoom into the HD file (15,120 × 10,080 pixels here) and the picture turns into the photos it is made of.



Want to see the photos fly into place? Watch the photo mosaic assembly video — we can render one for any mosaic.
Assembly takes minutes, not milliseconds, so the API is asynchronous: create a job, then poll it or wait for a webhook.
POST /v1/mosaicsSend 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.
GET /v1/mosaics/{id}Check the status: queued → processing → preview_ready (or failed with a reason).
When the status is preview_ready, the response carries preview_url — a watermarked image you can show to your user for approval.
POST /v1/mosaics/{id}/unlockSpend credits from your Collager.ai balance to unlock the mosaic. The response carries hd_url — the clean full-resolution file.
If you passed webhook_url, we POST the job object to it when the preview is ready or the job fails — no polling needed.
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.
The full contract is in openapi.yaml (OpenAPI 3.1; parts coming in v0.1 are marked x-status: v0.1). Base URL https://api.collager.ai/v1 (also https://collager.ai/v1).
| Endpoint | What it does |
|---|---|
POST/v1/mosaics | Create a mosaic job from a main photo and tile photos. Returns the job id. |
GET/v1/mosaics/{id} | Job status; preview_url when ready; failure reason if any. |
POST/v1/mosaics/{id}/start | Start assembly of a job that was collecting uploads from your users. |
POST/v1/mosaics/{id}/unlock | Spend credits and get hd_url, the clean full-resolution file. |
POST/v1/mosaics/{id}/layered | Build the layered PSB for print for an existing job. |
DEL/v1/mosaics/{id} | Delete the job's photos and all results right away. |
GET/v1/mosaics/{id}/layout | Every tile with its photo, position and size in pixels, level and colour (JSON; XML with ?format=xml). |
POST/v1/collages | Shape collage - a heart, a number, a word, a star made of photos - in seconds (Prefer: wait=25). |
GET/v1/collages/{id} · POST/unlock · DEL | Collage status and preview; spend one credit for the clean file; delete. |
GET/v1/shapes | Shapes and how many photos fill each (hearts of 27-164 photos, numbers, words, stars, flowers, your own mask). |
GET/v1/account | Credit balance, key type and limits. |
The details an integration needs - the same contract as in openapi.yaml.
Every request carries Authorization: Bearer <key> over HTTPS. A key is bound to one Collager.ai account and spends that account's credits.
Two kinds of keys: ck_live_… creates real jobs and can unlock HD files; ck_test_… creates jobs that end at a watermarked preview and never spend credits. Keep keys on your server — never in a browser or mobile app.
| Field | Type | Meaning |
|---|---|---|
main_image_url | URL, required | The picture to recreate. JPEG or PNG, publicly reachable or a pre-signed link. A face or a clear subject works best. |
tile_image_urls | array of URLs | Photos for the tiles, 30 to 10,000. A few hundred give a good result; with fewer photos tiles repeat. |
tiles_zip_url | URL | Or: one ZIP archive with all tile photos. |
tiles_source | object | Or: a cloud folder we read from — {"type": "s3", "bucket": "…", "prefix": "event-42/", "region": "eu-west-1"} (also gcs, azure). |
collect_uploads | boolean | Or: no photos yet — we return an upload_url where your users add photos themselves (see below). |
featured_tile_urls | array of URLs | Photos that must appear larger than the rest — the couple, the guest of honour, the team captain. |
secondary_tile_urls | array of URLs | A second, slightly smaller featured level. |
style | object | Tile layout, tile size, background blur, colour strength — see Style options. Defaults give our standard look. |
layered_file | boolean | Also build the layered PSB for print (takes longer). Can be requested later too. |
webhook_url | URL | Where we POST the job when the preview is ready or the job fails. |
metadata | object | Your own key–value strings (order id, user id); returned unchanged in every response and webhook. |
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.
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.
tile_image_urls: public or pre-signed links. We download them in parallel and skip broken ones (the job reports how many were used).
collect_uploads: true returns an upload_url: a mobile-friendly page where event guests, family or students add their own photos — the main photo and the tiles. Call POST /v1/mosaics/{id}/start when you have enough.
tiles_zip_url: a single link to a ZIP with all the photos. Not live yet — write to us if you need it and we'll prioritise it.
tiles_source: read-only access to an Amazon S3, Google Cloud Storage or Azure Blob folder, so nothing is re-uploaded. Not live yet — write to us.
multipart/form-data with the main photo and the tiles straight from your backend. Not live yet — today send links (option 1) or an upload link (option 2).
Dropbox or Google Drive folder, FTP, your photo platform's own API, a batch every night — tell us how your photos are stored and we'll set up a custom integration.
The main photo comes as main_image_url (or is uploaded on the upload page). JPEG and PNG work everywhere; tell us if you need HEIC or RAW.
The same controls our customers use on the site. Leave style out and you get the standard look: tiles of several sizes, so both the main picture and the small photos read well. Three styles of the same main photo and the same tiles:

The main picture is laid softly over the tiles: faces are clear from a distance, tiles stay visible up close. style left out.

People (or a pet) stay a clean photo, the mosaic is built around them — for gifts where faces must look exactly like the original. "clean_subject": true.

Less tinting: the picture is formed mostly by the tiles themselves, every photo keeps its own colours. "colorization": "low".
| Field | Values | Effect |
|---|---|---|
layout | variable (default) · uniform | Tiles of several sizes, or all tiles the same size. |
large_tiles | number, default 300 | How many of the largest tiles fit across the picture. Fewer — bigger photos you can look at; more — a more detailed main picture. |
size_levels | 1–4, default 4 | How many tile sizes: each level splits tiles into smaller ones where the picture needs detail. 1 = all tiles the same size. |
colorization | low · medium (default) · high | How strongly the tiles are tinted towards the main picture: low keeps the photos natural, high makes the main picture stand out. |
blur_background | 0–100 | Soften the background of the main picture so the subject stands out. |
clean_subject | boolean | Keep the main subject (a person, a pet) as a clean photo and build the mosaic only around it. |
Featured photos. Photos in featured_tile_urls get the largest tiles and are placed first, so the people who matter are easy to find in the mosaic. Two levels are possible — featured_tile_urls and secondary_tile_urls — like the gold and silver stars on our site.
preview_url — a JPEG with our watermark, sized for screens. Show it to your user before anything is paid.
hd_url after unlock — the clean JPEG at full resolution — for example 8,064 × 12,096 pixels for a portrait-shaped photo: enough for a large canvas or poster.
A Photoshop file with the mosaic and the main-picture layers separate, so a print shop can fine-tune colour and contrast. Built on request — set layered_file: true when you create the job, or call POST /v1/mosaics/{id}/layered after the preview is approved. Building it takes longer than the JPEG; psb_url appears when it is ready (webhook mosaic.layered_ready). It currently costs the same as the HD unlock; we may price it separately later.
layout_url — the full map of the mosaic: for every tile its photo, position, size and colour. Build your own zoomable mosaic on your site, let people find their photo, link each tile to a profile or an order.
tiles_archive_url — a ZIP of the tile images exactly as they sit in the mosaic, matching the layout file. For large sets we can give read access to the storage folder instead of one big archive.
# layout.json (fragment) { "width": 8064, "height": 12096, "tiles": [ {"photo": "tiles/0001.jpg", "source_url": "https://example.com/p/001.jpg", "x": 0, "y": 0, "w": 336, "h": 336, "featured": true, "avg_color": "#a37b5c"}, … ] }
<mosaic width="8064" height="12096"> <tile photo="tiles/0001.jpg" x="0" y="0" w="336" h="336" level="1" featured="true" avg_color="#a37b5c"/> <tile photo="tiles/0002.jpg" x="336" y="0" w="168" h="168" level="2" avg_color="#d9c7a1"/> … </mosaic>
viewer_url — a page where people zoom from the whole picture down to a single photo. Link to it or embed it in an iframe on your event or product page.
A 4K video where the photos fly into place and become the picture, with titles and music — see an example. Ordered per mosaic; via the API with POST /v1/mosaics/{id}/video (planned).
| Status | What happens |
|---|---|
collecting | Only with collect_uploads: the upload page is open; photos_received grows until you call /start. |
queued | Accepted, photos are being downloaded and checked. |
processing | The mosaic is being assembled on our render farm. This takes minutes and depends on the number of photos and the queue. |
preview_ready | preview_url is set: a watermarked image to show your user. |
unlocked | Credits spent, hd_url is set: the clean full-resolution file. |
failed | error says why (for example, too few readable photos). Failed jobs never spend credits. |
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 come as JSON: {"error": "insufficient_credits", "message": "…"}.
| HTTP | error | When |
|---|---|---|
| 400 | invalid_request | A field is missing or wrong, a photo cannot be downloaded or read. |
| 401 | unauthorized / invalid_key / key_revoked | No key, wrong key or revoked key. |
| 403 | test_key | A test key tried to unlock or order the PSB. |
| 402 | insufficient_credits | Not enough credits on the account to start or unlock. |
| 404 | not_found | No such job for this key. |
| 409 | not_ready | Unlock called before preview_ready. |
| 429 | rate_limited / too_many_jobs / daily_limit / busy | Too many requests or too many jobs running at once; see Retry-After. |
| 5xx | internal_error | Our side. Retry with the same Idempotency-Key. |
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.
We POST a JSON event (mosaic.preview_ready, mosaic.unlocked, mosaic.layered_ready, mosaic.failed, and collage.* for shape collages) 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.
The photos you send are used to build your mosaic and nothing else. They are never published, never shown to other customers, never sold and never used to train AI models.
Photos, previews and result files are deleted automatically 30 days after the job is created. Download the HD file or PSB within that time; a fresh link is available from GET /v1/mosaics/{id} until then.
DELETE /v1/mosaics/{id} removes the job's photos and all its results right away — use it when your user asks to be forgotten, or simply when you have your file.
Files are kept in Amazon S3 in Frankfurt and handed out only through time-limited signed links. Need a data processing agreement (GDPR) or a different retention period? Write to us.
Typical integrations we design the API for.
Guests upload photos through the upload link; one mosaic of everyone goes up on the screen and to every guest the same evening.
Add “photo mosaic” to your canvas and poster checkout: preview for the customer, layered PSB for your print operator.
Turn an album the user already has into a mosaic gift for an anniversary or a birthday — no re-upload, straight from your storage.
A class or graduation portrait made of every student's photos; the zoom viewer lets each of them find themselves.
Wedding and memorial platforms offer the mosaic as an add-on, with the couple or the family as featured photos.
An assistant that makes a photo mosaic on request: everything it needs is in openapi.yaml and llms.txt.
The API covers the common case. When your product needs something else, our own engineering team builds it with you.
Upload page, zoom viewer and previews on your domain with your logo and watermark — your customers never leave your product.
We read photos where they already live — your cloud, your photo platform's API, a nightly export — and send results back the same way.
A plugin for your CMS or e-commerce platform, print-ready files for your printer, assembly videos for your customers, live mosaic walls for events.
Tell us what you are building — or use the key request form below and describe it there.
Yes - API v0 is live. Request a key below; keys are issued by hand. Assistants can use the MCP server https://collager.ai/mcp without a key.
Minutes, not seconds — it depends on the number of photos and on the queue. That is why the API is asynchronous, with a webhook when the preview is ready.
At least 30; a few hundred give a good result. With fewer photos the tiles repeat, which is fine for small groups.
No self-serve free tier. For building and testing an integration we issue a test key that produces watermarked previews only.
Unlocking one HD mosaic spends one credit — the same credits as on collager.ai. Volume and white-label terms are set by agreement.
Yes: the upload page and the viewer can carry your logo, and the watermark on previews can be yours. Write to us about white-label.
An API key belongs to an ordinary Collager.ai account. No separate developer plan and no separate billing.
Unlocking one HD mosaic spends one credit — the same credits you buy on collager.ai.
There is no self-serve free tier. We read every request and issue keys ourselves; for building an integration we can give you a test key that returns watermarked previews only.
High volume, white-label or your own watermark: write to us — volume terms are set by agreement.
Building an assistant, an agent or a no-code automation? These are the machine-readable entry points.
collager.ai/llms.txt — what Collager.ai is and where everything lives, in plain text for language models.
collager.ai/developers/openapi.yaml — the v0 specification (OpenAPI 3.1).
https://collager.ai/mcp (Streamable HTTP, no sign-in): make_shape_collage, get_shape_collage, list_collage_shapes, list_mosaic_styles, start_photo_mosaic. Claude Code: claude mcp add --transport http collager-ai https://collager.ai/mcp
Agent card: /.well-known/agent-card.json (A2A 1.0, JSON-RPC at /a2a). Privacy for the API, MCP and plugins: collager.ai/developers/privacy.
Tell us what you are building. We read every request and reply from support@collager.ai.