Developers API

Welcome to the Mimi Panda API documentation. Our API allows you to programmatically access our AI-powered image transformation services including coloring page generation, paint-by-numbers creation, AI image generation, image upscaling, and AI filter application.

Base URL

https://mimi-panda.com/api

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

To obtain an API token, please login here https://mimi-panda.com/login to your personal account and go to the My profile page. Then click on the "Generate Token" button in the API Token section.

Response Format

Most endpoints return JSON. Successful requests return HTTP 200 with JSON bodies; errors use appropriate status codes with a JSON payload such as {"error": "..."}.

For paint-by-numbers file downloads (GET /service/item/{uuid}/pbn/download/{type} and GET /service/item/{uuid}/pbn/colors/{type}), the server returns a file attachment (SVG, PNG, PDF, JPEG, CSV, palette files, etc.) instead of JSON. Save the response body directly (for example use curl with -o).

Important for binary formats (PDF, PNG, JPEG, palette files): The response body is raw binary data. Do not attempt to decode it as UTF-8 or any other text encoding — doing so will corrupt the file. Read the response as bytes and write it to disk without any re-encoding. Text-based formats (csv, gpl, kpl, SVG) are safe to handle as UTF-8 text. For PBN color export type=swatches, the server may return either .swatches (30 colors or fewer) or .zip (more than 30 colors, containing multiple .swatches files).

Endpoints

Create Coloring Page from Image

POST /service/coloring

Convert an uploaded image into a coloring page using AI technology.

Request Parameters

Parameter Type Required Description
image file Yes Image file to convert. Accepted formats: jpg, png, webp, jpeg, heic, heif. Max size: 20MB
version string No API version to use. Options: v1, v2. Default: v2
type string No For v2: v2_general, v2_detailed, v2_anime, v2_simplified, v2_comic
For v1: image, photo
Default: v2_general (v2) or photo (v1)
smart_subject_focus boolean No When enabled, automatically detects and focuses on the main subject of the image for better coloring results. Default: false

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request

curl -X POST https://mimi-panda.com/api/coloring \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@/path/to/image.jpg" \
  -F "version=v2" \
  -F "type=v2_detailed"

Create Paint-by-Numbers

POST /service/pbn

Create a paint-by-numbers template from an uploaded image or AI-generated image from a text prompt.

Request Parameters

Parameter Type Required Description
image file No* Image file to convert. Accepted formats: jpg, png, webp, jpeg, heic, heif. Max size: 20MB
prompt string No* Text description for AI image generation (3-600 characters). *Either image or prompt must be provided
numberOfColors integer No Number of colors to be used for generating your paint by numbers (7-100). Default: 30
segmentsComplexity string No Controls the size and detail level of paint segments. Options: none, level1, level2, level3, simplest. Default: none
canvasSize string No Canvas size in inches (e.g., "12x16"). Max dimensions: 45x45 inches. Min dimensions: 4x4 inches. Default: none
crop boolean No Whether to crop the image to fully cover chosen canvas size. Default: false
cropCoordinates string (JSON) No Crop region as a JSON string with keys x1, y1, x2, y2 — each a normalized float between 0 and 1 relative to the image dimensions (0,0 = top-left, 1,1 = bottom-right). x2 must be greater than x1 and y2 must be greater than y1. Only applied when crop is true. Example: {"x1":0.1,"y1":0.1,"x2":0.9,"y2":0.9}
palette integer No Palette ID that should be used for generating your paint by numbers. Must be from your saved palettes
paletteColors string No Comma-separated list of color codes from the chosenpalette (minimum 7 colors)
aiFilterType string No AI art style to apply. Options: none, painting-general, painting-oil-painting, painting-palette-knife, painting-acrylic, painting-watercolor, painting-gouache, painting-digital, painting-graffiti, painting-grimdark, painting-impasto, painting-impressionism-painting-style, painting-magic-realism, painting-pointillism, painting-renaissance, painting-retrofuturism. Default: none
minArea integer|string No The minimum size (as a percentage of the shortest side of your image) that a color region must be to remain separate. Increasing this value will combine smaller color regions into larger ones. Default is 0 (no merging). "auto" means automatically detect the minimum size.
mode string No Options: polygon, pixel. Default: polygon. Selecting this option creates a PBN SVG file that precisely mirrors the pixel pattern of your processed image.
enhancement boolean No Enabling enhancement will clean up the processed image by removing small details and make zones easier to color, resulting in a smoother and simpler appearance but with reduced fine detail. Default: true
fixedNumbersSize boolean No When enabled, ensures that all number labels in the generated PBN have a consistent, uniform size. Default: false

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request (with Image)

curl -X POST https://mimi-panda.com/api/pbn \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@/path/to/image.jpg" \
  -F "numberOfColors=40" \
  -F "segmentsComplexity=level2"

Example Request (with Prompt)

curl -X POST https://mimi-panda.com/api/pbn \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "prompt=Beautiful sunset over mountains" \
  -F "numberOfColors=30" \

Generate AI Coloring Page from Prompt

POST /service/ai/coloring

Generate a coloring page using AI based on a text description.

Request Parameters

Parameter Type Required Description
prompt string Yes Text description of the desired coloring page (3-600 characters)
style string Yes Art style preset for the coloring page. Available styles: kids_coloring_page, teenagers_coloring_page, adults_coloring_page
aspectRatio string No Image aspect ratio. Options: 1x1, 2x3, 3x2, 4x3, 3x4, 9x16, 16x9
version string Yes API version. Options: v1, v2

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request

curl -X POST https://mimi-panda.com/api/ai/coloring \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A magical unicorn in an enchanted forest",
    "style": "fantasy",
    "aspectRatio": "3x4",
    "version": "v2"
  }'

Generate AI Image from Prompt

POST /service/ai/image

Generate high-quality AI images from text descriptions.

Request Parameters

Parameter Type Required Description
prompt string Yes Text description of the desired image (3-600 characters)
aspectRatio string Yes Image aspect ratio. Options: 1x1, 2x3, 3x2, 4x5, 5x4

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request

curl -X POST https://mimi-panda.com/api/ai/image \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night with neon lights",
    "aspectRatio": "16x9"
  }'

Upscale and Enhance Image

POST /service/image/upscale

Enhance and upscale an image using AI technology to improve quality and resolution.

Request Parameters

Parameter Type Required Description
image file Yes Image file to upscale. Accepted formats: jpg, png, webp, jpeg, heic, heif. Max size: 20MB. Max dimensions: 4000x4000px
upscale integer Yes Upscale factor. Options: 2, 4. Note: Images larger than 1000px will be automatically limited to 2x upscale

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request

curl -X POST https://mimi-panda.com/api/image/upscale \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@/path/to/image.jpg" \
  -F "upscale=4"

Apply AI Filter to Image

POST /service/image/filter

Transform an image by applying AI-powered artistic filters and effects.

Request Parameters

Parameter Type Required Description
image file Yes Image file to apply filter to. Accepted formats: jpg, png, webp, jpeg, heic, heif. Max size: 20MB
filterType string Yes Type of AI filter to apply. Contact support for available filter types
strength number Yes Filter strength. Options: 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Example Request

curl -X POST https://mimi-panda.com/api/image/filter \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@/path/to/image.jpg" \
  -F "filterType=artistic" \
  -F "strength=0.7"

Get Generated Item by UUID

GET /service/item/{uuid}

Retrieve the status and results of a previously created item using its unique identifier.

For PBN items that are ready, JSON includes three asset URLs (pbn, picture, source) plus structured color data. For the same downloads available in the web app (PNG/PDF outlines, grayscale, custom-colored SVGs, palette PDFs/CSV/software palettes, etc.), use the dedicated download PBN image and download PBN colors endpoints below.

URL Parameters

Parameter Type Required Description
uuid string Yes The unique identifier (key) returned when creating the item

Response

The response structure varies depending on the item type:

Coloring Page Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:35:23",
  "images": [
    "https://mimi-panda.com/storage/coloring/image.jpg"
  ]
}

Paint-by-Numbers Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:37:12",
  "images": {
    "pbn": "https://mimi-panda.com/storage/pbn/pbn-image.jpg",
    "picture": "https://mimi-panda.com/storage/pbn/picture.jpg",
    "source": "https://mimi-panda.com/storage/pbn/source.jpg"
  },
  "colors": [
    {
      "number": 1,
      "hex": "#FF5733",
      "name": "Red Orange"
    },
    {
      "number": 2,
      "hex": "#3498DB",
      "name": "Sky Blue"
    }
  ],
  "parameters": {
    "prompt": "Beautiful sunset",
    "numberOfColors": 30,
    "segmentsComplexity": "level2",
    "canvasSize": "16x16",
    "crop": false,
    "palette": null,
    "paletteColors": null,
    "aiFilterType": "none",
    "minArea": 0
  }
}

AI Coloring/Image Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:36:45",
  "images": [
    "https://mimi-panda.com/storage/catalog/image1.jpg",
    "https://mimi-panda.com/storage/catalog/image2.jpg"
  ],
  "parameters": {
    "prompt": "Magical unicorn in forest",
    "style": "fantasy",
    "aspectRatio": "3x4",
    "width": 1024,
    "height": 1365
  }
}

Image Upscale Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:36:12",
  "images": [
    "https://mimi-panda.com/storage/catalog/upscaled-image.jpg"
  ],
  "parameters": {
    "upscale": 4,
    "width": 4096,
    "height": 4096
  }
}

AI Filter Response

{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:35:45",
  "images": [
    "https://mimi-panda.com/storage/catalog/filtered-image.jpg"
  ],
  "parameters": {
    "filterType": "artistic",
    "strength": 0.7
  }
}

Status Values

  • in_queue - Task is waiting to be processed
  • processing - Task is currently being processed
  • ready - Task completed successfully, results are available
  • failed - Task failed to complete

Example Request

curl -X GET https://mimi-panda.com/api/item/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Download PBN Image File

GET /service/item/{uuid}/pbn/download/{type}

Download the paint-by-numbers or related rasterized assets in any format offered in the Profile app once the job status is ready. The UUID must belong to your account.

URL Parameters

Parameter Type Required Description
uuid string Yes The API key UUID returned when the PBN was created (same as used for GET /service/item/{uuid})
type string Yes SVG / raster source: origin (picture), pbn (numbered template), source (original upload), outlines, grayscale, originwithnumbers, custom
PNG (server uses Inkscape when exporting): outlinespng, grayscalepng, pbnpng, originpng
PDF (Inkscape): pbnpdf, outlinespdf, grayscalepdf, originpdf

Query Parameters (optional unless noted)

Parameter Type Required Description
width integer No Export width in pixels (1–15000). For PNG-export type values.
height integer No Export height in pixels (1–15000). For PNG-export type values.
download-type string Yes if type=custom pbn, outlines, or hybrid
download-strokes-color string Yes if type=custom Stroke color as a CSS color (e.g. #222222)
download-numbers-color string Yes if type=custom Number label color as a CSS color
download-hybrid-opacity decimal No When download-type=hybrid, opacity of filled regions (0–1). Default roughly 0.05.
download-frame string No yes or no — add a printable border frame (matches app behavior)

Responses

  • 200 — File body (Content-Disposition includes a filename)
  • 400 — Invalid type, missing parameters for custom, or invalid query validation
  • 401 — Missing or invalid token
  • 403 — UUID belongs to another user
  • 404 — UUID not found, missing files on storage, or not a PBN item
  • 409 — Item exists but status is not ready yet
  • 500 — Export failed (e.g. PDF generation)

Example: download outlines as SVG

curl -L -o pbn-outlines.svg \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/outlines" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example: download full PBN as PNG with width

curl -L -o pbn.png \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/pbnpng?width=3000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example: download full PBN as PDF

curl -L -o pbn.pdf \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/pbnpdf" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example: download grayscale as PDF

curl -L -o pbn-grayscale.pdf \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/grayscalepdf" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example: custom SVG (numbered template, colored strokes)

curl -L -o pbn-custom.svg \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/custom?download-type=pbn&download-strokes-color=%23000000&download-numbers-color=%23ffffff&download-frame=no" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Download PBN Colors File

GET /service/item/{uuid}/pbn/colors/{type}

Download the palette / color legend for a ready paint-by-numbers item in spreadsheet, PDF/image chart, or third-party palette formats (aligned with downloads in the Profile app).

URL Parameters

Parameter Type Required Description
uuid string Yes The API key UUID for the PBN item
type string Yes pdf — full color chart PDF
pdfshort — compact PDF chart
png — full chart as JPEG image
pngshort — compact chart as JPEG image
csv — CSV (codes, names, hex, RGB, HSL)
swatches — Procreate swatches export (.swatches if colors ≤ 30; .zip with multiple .swatches files if colors > 30)
gpl — GIMP palette
kpl — Krita palette

When using type=swatches, detect the exact returned format from the response metadata: check Content-Disposition for filename extension and X-Mimi-Colors-Format for swatches or zip.

Responses

  • 200 — File attachment (format depends on type)
  • 400 — Invalid color export type
  • 401, 403, 404, 409 — Same semantics as the PBN image download endpoint

Example Request

curl -L -o colors.csv \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/colors/csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP Status Codes

Code Description
200 Success - Request completed successfully
400 Bad Request - Invalid parameters or validation error
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions or quota exceeded
404 Not Found - Requested resource does not exist
409 Conflict - Resource exists but is not in a usable state yet (for example PBN downloads when status is not ready)
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong on our end

Error Response Format

{
  "error": "Detailed error message describing what went wrong"
}

Common Error Messages

  • Validation Errors: Specific field validation failures (e.g., "The image field is required")
  • File Errors: Issues with uploaded files (e.g., "Failed to process HEIC image")
  • Content Policy: "The prompt contains trademarks or other protected content"
  • Not Ready: Download endpoints return HTTP 409 when the underlying item exists but processing is not finished ("Item is not ready yet.")

Workflow Example

Here's a typical workflow for creating and retrieving a paint-by-numbers image:

Step 1: Create a Paint-by-Numbers

curl -X POST https://mimi-panda.com/api/pbn \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@/path/to/photo.jpg" \
  -F "numberOfColors=40" \
  -F "colorPrecision=high"

# Response:
{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_queue",
  "created": "2025-10-14 12:34:56"
}

Step 2: Check Status (Poll Periodically)

curl -X GET https://mimi-panda.com/api/item/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response (while processing):
{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:35:12"
}

Step 3: Retrieve Completed Result

curl -X GET https://mimi-panda.com/api/item/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response (when ready):
{
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "created": "2025-10-14 12:34:56",
  "updated": "2025-10-14 12:37:12",
  "images": {
    "pbn": "https://mimi-panda.com/storage/pbn/pbn-image.jpg",
    "picture": "https://mimi-panda.com/storage/pbn/picture.jpg",
    "source": "https://mimi-panda.com/storage/pbn/source.jpg"
  },
  "colors": [...],
  "parameters": {...}
}

Step 4 (optional): Download PBN files directly

When status is ready, you can fetch the same exports as in the Profile UI without parsing stored URLs manually:

# Numbered outlines only (SVG)
curl -L -o outlines.svg \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/download/outlines" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Color palette as CSV
curl -L -o colors.csv \
  "https://mimi-panda.com/api/service/item/550e8400-e29b-41d4-a716-446655440000/pbn/colors/csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

  • Polling: When checking item status, poll every 3-5 seconds. Most operations complete within 30-60 seconds.
  • Image Optimization: Compress images before uploading to reduce processing time and bandwidth usage.
  • Error Handling: Implement proper error handling and retry logic for failed requests.
  • Rate Limiting: Respect rate limits and implement exponential backoff for retries.
  • Security: Never expose your API token in client-side code. Always make API calls from your backend.
  • Content Policy: Ensure prompts and images comply with our content policy to avoid rejected requests.
  • PBN file downloads: Use GET /service/item/{uuid}/pbn/download/{type} and GET /service/item/{uuid}/pbn/colors/{type} only after GET /service/item/{uuid} reports status: ready. Save the raw response body; treat 409 as "still processing."
  • Binary response handling: PDF, PNG, and JPEG downloads return raw binary data. If you are consuming the API in code (not curl), read the response as bytes — never pass it through a text decoder (e.g. UTF-8) before writing to disk, as this will corrupt the file by replacing invalid byte sequences with replacement characters.

Support

If you have questions or need assistance with the API:

  • Email: [email protected]
  • Documentation Updates: Check this page regularly for updates and new features
  • Status Page: Monitor our service status and planned maintenance
Back to Top
Cookie Consent reset
We use cookies
We use essential cookies to make our site work. Analytics cookies help us improve your experience. You can find more information in our cookie policy. Cookie policy
Accept only essential Accept all
We use cookies Customize
Accept