---
title: "Create a mosaic job"
method: POST
path: "/mosaics"
tags: ["mosaics"]
---

# Create a mosaic job

`POST /mosaics`

## Request

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

## Headers

- `Idempotency-Key` string

## Request body

- CreateMosaicRequest: Pass the tiles as links (tile_image_urls, plus optional featured/secondary) or use collect_uploads. tiles_zip_url, tiles_source and multipart upload arrive in v0.1. Other storage (Dropbox, Google Drive, FTP, your platform's API) - custom integration on request.
  - `main_image_url` string, uri: The picture to recreate. Required unless collect_uploads.
  - `tile_image_urls` string[]: Photos for the tiles (public or pre-signed links). At least 30 tiles in total; a few hundred give a good result.
  - `tiles_zip_url` string, uri: One ZIP archive with all tile photos (v0.1).
  - `tiles_source` object: Cloud folder we read the tiles from (v0.1).
    - `type` 's3' | 'gcs' | 'azure'
    - `bucket` string
    - `prefix` string
    - `region` string
  - `featured_tile_urls` string[]: Photos that get the largest tiles and are placed first.
  - `secondary_tile_urls` string[]: Second featured level, slightly smaller.
  - `style` object: Omit for the standard look (the engine picks the style for the main photo).
    - `layout` 'variable' | 'uniform'
    - `large_tiles` integer: How many of the largest tiles fit across the picture (variable 0 = auto or 50-5000; uniform 200-5000, default 2000).
    - `size_levels` integer
    - `colorization` 'low' | 'medium' | 'high'
    - `blur_background` integer
    - `clean_subject` boolean: Keep the main subject as a clean photo, mosaic only around it.
  - `layered_file` boolean: Also build the layered PSB for print (takes longer).
  - `collect_uploads` boolean: No photos yet - the response carries upload_url, a page where your users add photos; status stays collecting until POST /mosaics/{id}/start.
  - `webhook_url` string, uri: Called with a WebhookEvent when the preview is ready, the job fails, is unlocked or the PSB is ready.
  - `metadata` object: Your own key-value pairs, returned unchanged.

## Response `200`

Same Idempotency-Key as an earlier request - that job is returned.

- Mosaic
  - `id` string, required
  - `object` 'mosaic', required
  - `status` 'collecting' | 'fetching' | 'queued' | 'processing' | 'preview_ready' | 'unlocked' | 'failed', required: fetching - we are downloading your links; queued/processing - in the build farm.
  - `upload_url` string, uri, nullable: With collect_uploads - the page where your users add photos.
  - `photos_received` integer, nullable: With collect_uploads - photos uploaded so far.
  - `preview_url` string, uri, nullable: Watermarked preview, set from preview_ready on. Link valid 24 h.
  - `hd_url` string, uri, nullable: Clean full-resolution file, set after unlock. Link valid 24 h.
  - `psb_status` 'building' | 'ready' | 'failed' | 'null', nullable
  - `psb_url` string, uri, nullable: Layered PSB for print, when built. Link valid 24 h.
  - `layout_url` string, uri, nullable: GET it with your key - every tile with photo, position, size, colour. JSON by default, XML with ?format=xml. Set from preview_ready on.
  - `tiles_archive_url` string, uri, nullable: ZIP of the tile images as placed in the mosaic (v0.1). Large sets - read access to a storage folder by agreement.
  - `viewer_url` string, uri, nullable: Interactive zoom viewer page (v0.1).
  - `width` integer, nullable
  - `height` integer, nullable
  - `tiles_used` integer, nullable
  - `tiles_failed` integer: Links we could not download (they are skipped).
  - `style` object, nullable
  - `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
  - `expires_at` string, date-time, required: When photos and results are deleted automatically (30 days after creation).
  - `created_at` string, date-time, required

## Other responses

- `202`: Job accepted; status fetching (we download your links) or collecting.
- `400`: Error.
- `401`: Error.
- `402`: Live key on an account with no credits.
- `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)