CandyMuse API

01 · Quickstart

Create your first task

Send a required text prompt. A reference image is optional. The response is a task; generation continues after the request returns.

curl -X POST https://candymuse.ai/api/create_image \
  -H "API-KEY: $API_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic night portrait with soft neon light",
    "quality": "low"
  }'

02 · Authentication

Send your API key as a header

Create, task polling, balance, and canonical result requests require the same API-KEY header. The completed task's short-lived output_url does not require that header. Keep both credentials server-side.

03 · Image generation

Prompt-based image generation

A prompt is required. Include input_image_base64 only when a reference should guide the generated image. Image requests do not select a preset.

curl -X POST https://candymuse.ai/api/create_image \
  -H "API-KEY: $API_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic night portrait with soft neon light",
    "quality": "low"
  }'

Guide the result with a reference

Add a PNG, JPEG, or WebP reference while keeping the prompt. The reference is optional for both quality levels.

curl -X POST https://candymuse.ai/api/create_image \
  -H "API-KEY: $API_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Use the reference subject in a cinematic night portrait with soft neon light",
    "input_image_base64": "<BASE64_IMAGE>",
    "quality": "high"
  }'

These are the complete Image API fields. Any additional field is rejected.

$0.020 / $0.025 low / high per accepted task; a terminal failure is refunded once in full.

04 · Native-audio video

Native-audio video generation

Both paths address the same production pipeline. Every completed result contains H.264 video and native AAC audio.

curl -X POST https://candymuse.ai/api/create_video \
  -H "API-KEY: $API_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "input_image_base64": "...",
    "preset_name": "default",
    "quality": "low",
    "video_length": "5s",
    "age_check": true
  }'

$0.150 charged when accepted; a terminal failure is refunded once in full.

05 · Tasks and results

Poll once, download privately

Poll every 6–10 seconds and respect Retry-After. Stop when the task reaches COMPLETED or FAILED.

curl https://candymuse.ai/api/task/$TASK_ID \
  -H "API-KEY: $API_KEY"

{
  "id": "job_...",
  "created_at": "2026-08-14T01:23:45.000000Z",
  "updated_at": "2026-08-14T01:24:08.000000Z",
  "status": "COMPLETED",
  "task_message": null,
  "preset_name": null,
  "prompt": null,
  "input_image_url": null,
  "input_image2_url": null,
  "output_url": "https://candymuse.ai/api/result-cap/...",
  "tasks_in_queue": null,
  "cost_symbol": "USD",
  "cost_amount": "0.020",
  "quality": "low",
  "input_image_provided": false
}

The response always includes the fields shown above. prompt is never echoed, an image task returns preset_name as null, later task reads normally return input_image_url as null, output_url appears only after completion, and a failed task carries its error in task_message.

Download the result

A completed task includes a 6-hour output_url bearer credential. It supports bare GET, HEAD, and one HTTP byte range. Do not log or share the complete URL. Fetching the completed task again signs a fresh 6-hour URL without rerunning or recharging the task.

For a stable authenticated path, use GET or HEAD /api/result/{task_id} with API-KEY; a single byte Range is also supported. Results are streamed through CandyMuse, so private storage keys are never exposed.

06 · Errors and limits

Predictable JSON errors

{
  "error": {
    "code": "invalid_request",
    "message": "Request fields are invalid."
  }
}

Validation and operation errors use the envelope above. Missing or invalid keys on create, task, and balance routes currently use FastAPI's {"detail":"..."} authentication response.

• Maximum JSON request body: 22,020,096 bytes.
• Maximum decoded image size: 15 MiB (15,728,640 bytes).
• Minimum image dimensions: 64 pixels on each side.
• Maximum decoded image area: 16,000,000 pixels.
• Controlled beta default: 12 create, task-poll, or balance requests per key per fixed minute.
• Authenticated invalid requests also consume that fixed-window request allowance.
• Controlled beta default: 2 active jobs per key and 4 per account.

07 · Reference

Supporting endpoints