close
Collager.ai
Photo Mosaic & Collage API · v0 live

Hundreds of photos in, one portrait out.

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.

API v0 is live. Keys are issued by hand - request one below. Everything marked v0.1 (ZIP and cloud-folder input, mosaic multipart upload, tile archive, zoom viewer) is coming next. AI assistants can call our MCP server 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.

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.

Main photo: a couple on the beach
main_image_url — the picture to recreate
Photo mosaic of the same couple made of hundreds of small photos
Result — every tile is one of your tile_image_urls

Every tile is a real photo

Zoom into the HD file (15,120 × 10,080 pixels here) and the picture turns into the photos it is made of.

Photo mosaic portrait of a woman made of thousands of small photos
1× the whole picture
Close-up of the face in the photo mosaic: eyes, nose and lips built from small photos
5× the face is built from tiles
Extreme close-up of the eye in the photo mosaic: the pupil is a photo of a black cat
17× each tile is a photo you can recognise

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}

Endpoints

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).

EndpointWhat it does
POST/v1/mosaicsCreate 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}/startStart assembly of a job that was collecting uploads from your users.
POST/v1/mosaics/{id}/unlockSpend credits and get hd_url, the clean full-resolution file.
POST/v1/mosaics/{id}/layeredBuild 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}/layoutEvery tile with its photo, position and size in pixels, level and colour (JSON; XML with ?format=xml).
POST/v1/collagesShape collage - a heart, a number, a word, a star made of photos - in seconds (Prefer: wait=25).
GET/v1/collages/{id} · POST/unlock · DELCollage status and preview; spend one credit for the clean file; delete.
GET/v1/shapesShapes and how many photos fill each (hearts of 27-164 photos, numbers, words, stars, flowers, your own mask).
GET/v1/accountCredit balance, key type and limits.

API reference

The details an integration needs - the same contract as in openapi.yaml.

Authentication and keys

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.

Create a mosaic — request fields

FieldTypeMeaning
main_image_urlURL, requiredThe picture to recreate. JPEG or PNG, publicly reachable or a pre-signed link. A face or a clear subject works best.
tile_image_urlsarray of URLsPhotos for the tiles, 30 to 10,000. A few hundred give a good result; with fewer photos tiles repeat.
tiles_zip_urlURLOr: one ZIP archive with all tile photos.
tiles_sourceobjectOr: a cloud folder we read from — {"type": "s3", "bucket": "…", "prefix": "event-42/", "region": "eu-west-1"} (also gcs, azure).
collect_uploadsbooleanOr: no photos yet — we return an upload_url where your users add photos themselves (see below).
featured_tile_urlsarray of URLsPhotos that must appear larger than the rest — the couple, the guest of honour, the team captain.
secondary_tile_urlsarray of URLsA second, slightly smaller featured level.
styleobjectTile layout, tile size, background blur, colour strength — see Style options. Defaults give our standard look.
layered_filebooleanAlso build the layered PSB for print (takes longer). Can be requested later too.
webhook_urlURLWhere we POST the job when the preview is ready or the job fails.
metadataobjectYour 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.

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.

1. List of photo URLs

tile_image_urls: public or pre-signed links. We download them in parallel and skip broken ones (the job reports how many were used).

2. Upload link for your users

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.

3. One ZIP archive — coming soon

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.

4. Your cloud bucket — coming soon

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.

5. Direct file upload — coming soon

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).

6. Something else

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.

Style options

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:

Soft classic style: faces and the mosaic blend evenly
Soft classic — the default
What it does

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

Clean subject style: the family stays a clean photo, mosaic around them
Clean subject
What it does

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.

Stronger mosaic style: the picture is formed mostly by the tiles themselves
Stronger mosaic
What it does

Less tinting: the picture is formed mostly by the tiles themselves, every photo keeps its own colours. "colorization": "low".

FieldValuesEffect
layoutvariable (default) · uniformTiles of several sizes, or all tiles the same size.
large_tilesnumber, default 300How many of the largest tiles fit across the picture. Fewer — bigger photos you can look at; more — a more detailed main picture.
size_levels1–4, default 4How many tile sizes: each level splits tiles into smaller ones where the picture needs detail. 1 = all tiles the same size.
colorizationlow · medium (default) · highHow strongly the tiles are tinted towards the main picture: low keeps the photos natural, high makes the main picture stand out.
blur_background0–100Soften the background of the main picture so the subject stands out.
clean_subjectbooleanKeep 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.

What you get

Watermarked preview

preview_url — a JPEG with our watermark, sized for screens. Show it to your user before anything is paid.

HD file

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.

Layered PSB for print

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 file — JSON or XML

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.

The tile photos

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"},
    …
  ]
}
The same layout as XML
<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>

Add-ons

Interactive zoom viewer

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.

Assembly video

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).

Job statuses

StatusWhat happens
collectingOnly with collect_uploads: the upload page is open; photos_received grows until you call /start.
queuedAccepted, photos are being downloaded and checked.
processingThe mosaic is being assembled on our render farm. This takes minutes and depends on the number of photos and the queue.
preview_readypreview_url is set: a watermarked image to show your user.
unlockedCredits spent, hd_url is set: the clean full-resolution file.
failederror 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

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

HTTPerrorWhen
400invalid_requestA field is missing or wrong, a photo cannot be downloaded or read.
401unauthorized / invalid_key / key_revokedNo key, wrong key or revoked key.
403test_keyA test key tried to unlock or order the PSB.
402insufficient_creditsNot enough credits on the account to start or unlock.
404not_foundNo such job for this key.
409not_readyUnlock called before preview_ready.
429rate_limited / too_many_jobs / daily_limit / busyToo many requests or too many jobs running at once; see Retry-After.
5xxinternal_errorOur side. Retry with the same Idempotency-Key.

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.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.

Photos, storage and deletion

Used only for your mosaic

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.

Kept 30 days, then deleted

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 at any moment

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.

Stored in the EU

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.

Who builds with it

Typical integrations we design the API for.

Events and conferences

Guests upload photos through the upload link; one mosaic of everyone goes up on the screen and to every guest the same evening.

Print shops and photo labs

Add “photo mosaic” to your canvas and poster checkout: preview for the customer, layered PSB for your print operator.

Photo apps and cloud albums

Turn an album the user already has into a mosaic gift for an anniversary or a birthday — no re-upload, straight from your storage.

Schools and universities

A class or graduation portrait made of every student's photos; the zoom viewer lets each of them find themselves.

Weddings and family gifts

Wedding and memorial platforms offer the mosaic as an add-on, with the couple or the family as featured photos.

AI assistants and agents

An assistant that makes a photo mosaic on request: everything it needs is in openapi.yaml and llms.txt.

Custom integrations

The API covers the common case. When your product needs something else, our own engineering team builds it with you.

Your brand, your domain

Upload page, zoom viewer and previews on your domain with your logo and watermark — your customers never leave your product.

Your storage and your platform

We read photos where they already live — your cloud, your photo platform's API, a nightly export — and send results back the same way.

Plugins and print

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.

Questions

Can I use the API today?

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.

How long does one mosaic take?

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.

How many photos do I need?

At least 30; a few hundred give a good result. With fewer photos the tiles repeat, which is fine for small groups.

Is there a free tier?

No self-serve free tier. For building and testing an integration we issue a test key that produces watermarked previews only.

What does it cost?

Unlocking one HD mosaic spends one credit — the same credits as on collager.ai. Volume and white-label terms are set by agreement.

Can I use my own branding?

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.

Keys and credits

Your regular account

An API key belongs to an ordinary Collager.ai account. No separate developer plan and no separate billing.

Same credits as the site

Unlocking one HD mosaic spends one credit — the same credits you buy on collager.ai.

Keys issued by hand

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.

For AI agents and tools

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

llms.txt

collager.ai/llms.txt — what Collager.ai is and where everything lives, in plain text for language models.

OpenAPI

collager.ai/developers/openapi.yaml — the v0 specification (OpenAPI 3.1).

MCP server

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

A2A and privacy

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.

Request an API key

Tell us what you are building. We read every request and reply from support@collager.ai.

We use your email only to reply about API access. See our privacy policy.

Thank you — your request is in. We'll write to you from support@collager.ai to set up your key.