API Documentation

Getting Started

1. Subscribe to the Commercial plan

API access is available exclusively on the Commercial plan ($43.99/month, 800 credits).

2. Generate an API key

Once subscribed, go to the Pricing page and scroll to the "API Keys" section. Click "Generate Key" and copy your key. It will only be shown once.

3. Authenticate your requests

Include your API key in the Authorization header:

Authorization: Bearer us_live_YOUR_API_KEY_HERE

Base URL

https://mosaic-api.fly.dev

Endpoints

Generate (Single Image)

Parameter	Type		Description
image	file	required	Image file (PNG, JPEG, WebP). Max 10 MB.
mode	string	optional	hex (mosaic), voronoi, cbn (color by number), lineart (coloring page), ai (AI coloring). Default: hex
output	string	optional	zip, mystery, answer, legend, full, beauty, svg. Default: zip
colors	int	optional	Number of colors (4–20). Default: 12
page	string	optional	letter, a4. Default: letter
preset	string	optional	Use a preset (overrides other params). See /api/presets
detail	string	optional	Lineart detail: simple, standard, detailed, expert
density	string	optional	Voronoi density: easy, standard, detailed, expert
hint	string	optional	Subject hint for AI mode (e.g. "a cat")

Example — Coloring page:

curl -X POST https://mosaic-api.fly.dev/api/generate \
  -H "Authorization: Bearer us_live_YOUR_KEY" \
  -F "image=@photo.jpg" \
  -F "mode=lineart" \
  -F "output=zip" \
  -o coloring-page.zip

Example — Color by Number:

curl -X POST https://mosaic-api.fly.dev/api/generate \
  -H "Authorization: Bearer us_live_YOUR_KEY" \
  -F "image=@photo.jpg" \
  -F "mode=cbn" \
  -F "colors=10" \
  -o color-by-number.zip

Bulk Generate

curl -X POST https://mosaic-api.fly.dev/api/bulk \
  -H "Authorization: Bearer us_live_YOUR_KEY" \
  -F "images=@photo1.jpg" \
  -F "images=@photo2.jpg" \
  -F "images=@photo3.jpg" \
  -F "mode=lineart" \
  -o bulk-coloring.zip

AI Image Generation

Parameter	Type		Description
prompt	string	required	Text description (3–1000 chars)
style	string	optional	coloring, cartoon, realistic, pixel-art, watercolor, sticker. Default: coloring
size	string	optional	1024x1024, 1024x1536, 1536x1024. Default: 1024x1024
quality	string	optional	low (1 credit), medium (3 credits), high (10 credits). Default: low

curl -X POST https://mosaic-api.fly.dev/api/ai-image \
  -H "Authorization: Bearer us_live_YOUR_KEY" \
  -F "prompt=a cute unicorn in a flower garden" \
  -F "style=coloring" \
  -F "quality=low" \
  -o ai-coloring.png

Check Balance

curl https://mosaic-api.fly.dev/api/credits/balance \
  -H "Authorization: Bearer us_live_YOUR_KEY"

Response:

{
  "balance": 742,
  "monthly_quota": 800,
  "plan_name": "commercial",
  "sub_status": "active"
}

List Presets

Credit Costs

Tool	Credits
Coloring Page (lineart)	1
Color by Number (cbn)	1
Mystery Mosaic (hex/voronoi)	1
AI Image — Standard	1
AI Image — HD	3
AI Image — Ultra HD	10
Bulk generation	1 per image

Rate Limits

API requests are subject to rate limits to ensure fair usage:

• Generation endpoints are processed one at a time (server-side semaphore)
• Maximum 50 images per bulk request
• Maximum 10 MB per image

Exceeding rate limits returns a 429 status code. Wait and retry.

Error Codes

Code	Meaning
400	Bad request (invalid parameters, unsupported image type)
401	Unauthorized (missing or invalid API key)
402	Insufficient credits
403	Forbidden (feature not available on your plan)
429	Rate limit exceeded
502	Upstream AI service error

Managing API Keys

You can manage your API keys from the Pricing page when logged in with a Commercial plan. You can also use these endpoints:

Support

For API questions or issues, contact us at hello@univers.studio.