Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

Create from Image

Upload your existing mascot design and let the API auto-detect the character.

Upload Your Image

You can upload an image either as a multipart form upload or by providing a URL to an existing image. Multipart uploads require a binary file field and a valid boundary; malformed bodies or missing files return HTTP 400. Let your HTTP client set the multipart boundary.

Multipart Upload

curl -X POST https://api.masko.ai/v1/upload \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -F "file=@mascot.png"

URL Upload

URL imports accept public HTTP(S) images up to 10 MB, with a 15-second download deadline. Every redirect must also resolve to a public address. Private network addresses and URLs containing credentials are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. These limits also apply to reference image URLs when creating a mascot or adding a reference.

curl -X POST https://api.masko.ai/v1/upload \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/my-mascot.png" }'

Animate immediately

To animate this image without a separate mascot creation call, use POST /v1/animations with source_image_asset_id, animation_prompt, and create_mascot: { "project_id": "PROJECT_ID" }. The model supplies only a name when create_mascot.name is omitted; no character description is generated. Save the returned mascot_id and use it for future animations. See upload and animate.

Create Mascot

Pass the asset_id from the upload step as a reference. You don't need to provide a prompt - the image itself is the reference, and the API extracts the character description automatically. If you omit name, it's also auto-detected from the image.

curl -X POST https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_ID",
    "reference_asset_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

How Auto-Analysis Works

When you create a mascot from an image, Masko uses AI vision to analyze the reference and extract a character name and detailed prompt. This analysis is free and happens automatically. The extracted prompt describes the character's visual traits so future generations stay consistent.

Adding More References

You can add up to 6 reference images to a mascot. More references means better consistency across generated poses.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/references \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

You can also pass a url instead of asset_id if you have a public image URL.

When references change, the style card is cleared and will be re-extracted on the next generation to reflect the updated visual direction.

Best Practices

  • Use 3-4 reference images showing different angles for best consistency
  • Keep a consistent art style across all references - don't mix 3D and flat vector
  • Use high-resolution images (1024x1024 or larger recommended)
  • White or transparent backgrounds work best - the AI focuses on the character, not the scene

Animate the uploaded image directly

You do not need to generate a new pose. For a new mascot, use upload and animate to create it in the animation request, or create it separately as shown above. For an existing mascot, pass an unattached upload directly to its generation endpoint:

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Idempotency-Key: animate-my-upload-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Gentle wave",
    "source_image_asset_id": "UPLOADED_IMAGE_ASSET_ID",
    "animation_prompt": "Wave gently, keeping the feet planted.",
    "animation_model": "standard",
    "duration": 5,
    "loop": true
  }'

This returns 202 with a job ID. Poll /v1/jobs/{job_id} for completion. Standard at 5 seconds costs 10 credits, with no image-generation charge. The original upload is preserved. Before animation, horizontal and vertical images are center-cropped to square and saved as a separate 1024 × 1024 source. Square inputs are used directly. To position the crop yourself, pass source_image_crop with x, y, width, and height in pixels. See image framing for an example. Video models may still alter details as they animate the image.

An unattached upload is imported as a source image under the destination mascot. It does not replace the mascot identity or become a reference automatically. Use the references endpoint separately if you want it to guide future poses. Pass an approved variant_id to associate a fresh upload with that variant. Existing generated images retain their saved context; selecting a conflicting variant still returns 409. Reuse the same idempotency key and unchanged request after an uncertain response to avoid duplicate generation charges.