Generation

A single unified endpoint handles all generation types: images, animations, logos, and edits. Each request creates a job you can poll for results.

POST/v1/collections/:id/generate

Image Generation

Generate a mascot image from a text prompt. Costs 1 credit. Returns both a full image and a transparent (background-removed) variant.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "name": "Waving hello",
    "image_prompt": "waving hello with a friendly smile"
  }'

Response includes asset_ids.image and asset_ids.transparent_image for the two variants.

Animation Generation

Generate an animated mascot from scratch. Costs 21 credits for a 4-second animation (1 credit for the image + 5 credits/sec for the video). Returns image, video, webm, and hevc assets.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Dancing",
    "image_prompt": "standing in a dance pose, arms raised",
    "animation_prompt": "dancing energetically with bouncy movements",
    "duration": 4,
    "loop": true
  }'

Animate Existing Image

Animate an image you already have. Pass source_image_asset_id to skip image generation. Costs 20 credits for 4 seconds (video only, no image cost).

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Waving animated",
    "source_image_asset_id": "IMAGE_ASSET_ID",
    "animation_prompt": "waving hello smoothly",
    "duration": 4
  }'

Transitions

Create a transition between two poses by providing both a source and end image. Set auto_reverse to automatically generate the return transition at no extra cost.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Idle to Wave",
    "source_image_asset_id": "IDLE_IMAGE_ID",
    "end_image_asset_id": "WAVE_IMAGE_ID",
    "animation_prompt": "transitioning from idle to waving",
    "auto_reverse": true,
    "reverse_name": "Wave to Idle"
  }'

When auto_reverse is true, the response includes a reverse_job object with its own job ID and asset IDs. The reverse costs 0 credits.

Edit Image

Modify an existing image with natural language instructions. Costs 1 credit.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "edit",
    "item_id": "EXISTING_ITEM_ID",
    "source_image_asset_id": "IMAGE_ASSET_ID",
    "edit_instructions": "Add a santa hat and snow falling in the background"
  }'

Logo Pack

Generate a full logo pack with multiple style variants. Costs 20 credits. Requires a Pro plan or higher.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "logo",
    "name": "App Logo",
    "logo_description": "Iconic representation of the character face",
    "logo_style_name": "Flat",
    "logo_style_instruction": "Flat design with solid colors, no gradients or shadows"
  }'

Batch Generation

Generate multiple items in a single request. Each item in the batch follows the same format as the single generate endpoint.

POST/v1/collections/:id/generate-batch
curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate-batch \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "image", "name": "Waving", "image_prompt": "waving hello" },
      { "type": "image", "name": "Thinking", "image_prompt": "thinking with hand on chin" },
      { "type": "animation", "name": "Dancing", "image_prompt": "dancing pose", "animation_prompt": "dancing", "duration": 4 }
    ]
  }'

Preview

Test a generation prompt without creating items or spending credits. Returns a temporary preview image URL.

POST/v1/generate/preview
curl -X POST https://api.masko.ai/v1/generate/preview \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "COLLECTION_ID",
    "prompt": "a friendly fox mascot waving hello"
  }'

Polling Jobs

Every generation returns a job_id. Poll the job endpoint to check progress. Use ?wait=true for long polling - the server holds the connection until the job completes or times out.

GET/v1/jobs/:id
# Standard polling
curl https://api.masko.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Long polling (waits for completion)
curl https://api.masko.ai/v1/jobs/JOB_ID?wait=true \
  -H "Authorization: Bearer masko_YOUR_API_KEY"
Tip

CDN URLs are returned immediately in the generate response, before generation finishes. You can embed these URLs in your app right away - they serve a placeholder until the real asset is ready, then automatically switch over.