Wixma API Reference

Quickstart

1. 1. Open Settings, create an API key, choose scopes, budgets, rate limit, and allowed tools.
2. 2. Upload images with POST /api/v1/uploads, reuse a generation output_url, or pass a supported image reference object.
3. 3. Start a job with POST /api/v1/generations.
4. 4. Poll GET /api/v1/generations/{id} until status is completed or failed.

curl https://wixma.ai/api/v1/generations \
  -H "Authorization: Bearer wx_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-shot-001" \
  -d '{
    "tool": "generator",
    "input": { "prompt": "A premium studio product photo of a red sneaker" },
    "options": { "quality": "medium", "aspect_ratio": "1:1", "output_format": "png" }
  }'

Core Concepts

Authentication, Scopes, and Budgets

Send your key as Authorization: Bearer wx_live_.... API access requires an active paid subscription. Keys can be scoped, paused, revoked, limited by tool, rate-limited, and capped by monthly/total/per-request credits.

Images: Uploads, URLs, History, and IDs

Image fields accept safe HTTPS image URLs or reference objects. Supported formats are PNG, JPEG, and WEBP up to 50MB.

{
  "input": {
    "images": [
      { "upload_id": "upload_uuid_here" },
      { "generation_id": "generation_uuid_here" },
      "https://wixma.ai/storage/v1/object/public/input_images/example.jpg"
    ]
  }
}

Concurrency and Job Limits

pending and processing generations count as active jobs. If the limit is reached, create calls return queue_limit_exceeded.

Endpoints

Tool: Image Generator

Creates a new image from text only.

Tool: Image Editor

Edits one or more reference images with a prompt. Reference images are visual context; include the most important image first.

Tool: AI Photographer

AI Photographer is a set of guided photo-editing tools. The API and MCP tools use the same backend prompt builders as the dashboard. You send controlled mode values; Wixma expands them into the detailed internal prompts automatically.

input.text_prompt is only an optional additional instruction. It does not replace the backend prompt. For example, use it for constraints like "keep the same expression" or placement details.

mode: "carousel" is special: GPT-5 mini first creates a 10-frame shot plan, then Wixma generates 10 separate images. The billed credit cost is 10 × selected image quality + 10 planner credits, and the job uses 2 generation slots while pending or processing.

Tool: Upscaler

Upscales a source image. Finish settings are intentionally not exposed through the public API.

Shared Option Reference

Aspect ratios

Quality

Output formats

Examples

const form = new FormData()
form.append("file", file)

const upload = await fetch("https://wixma.ai/api/v1/uploads", {
  method: "POST",
  headers: { Authorization: "Bearer wx_live_..." },
  body: form
}).then(r => r.json())

await fetch("https://wixma.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer wx_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": "edit-001"
  },
  body: JSON.stringify({
    tool: "editor",
    input: {
      images: [{ upload_id: upload.upload.id }],
      prompt: "Make the background look like a luxury studio."
    },
    options: { quality: "medium", aspect_ratio: "4:5" }
  })
})

{
  "tool": "photographer",
  "input": {
    "main_image": { "generation_id": "previous_generation_uuid" },
    "angle": "eye level, left side",
    "text_prompt": "Keep the same outfit and expression."
  },
  "options": {
    "mode": "angle_change",
    "quality": "high",
    "aspect_ratio": "4:5"
  }
}

{
  "tool": "photographer",
  "input": {
    "main_image": { "generation_id": "previous_generation_uuid" },
    "text_prompt": "Create a fashion carousel with the same scene, varied angles, detail shots, POV moments, and one full-body hero shot."
  },
  "options": {
    "mode": "carousel",
    "quality": "medium",
    "aspect_ratio": "4:5"
  }
}

async function waitForGeneration(id) {
  while (true) {
    const res = await fetch(`https://wixma.ai/api/v1/generations/${id}`, {
      headers: { Authorization: "Bearer wx_live_..." }
    })
    const data = await res.json()
    const generation = data.generation
    if (generation.status === "completed" || generation.status === "failed") return generation
    await new Promise(resolve => setTimeout(resolve, 3000))
  }
}

Responses

{
  "object": "response",
  "request_id": "req_...",
  "generation": {
    "id": "gen_uuid",
    "object": "generation",
    "status": "pending",
    "tool": "generator",
    "output_url": null,
    "input_image": null,
    "cost_credits": 110,
    "error_code": null,
    "error": null,
    "created_at": "2026-06-07T10:00:00.000Z"
  }
}

{
  "object": "error",
  "error": {
    "code": "queue_limit_exceeded",
    "message": "Your plus plan allows 4 active generation slots at once. This request needs 2 slots.",
    "details": { "active": 4, "limit": 4, "plan": "plus", "requiredSlots": 2 }
  },
  "request_id": "req_..."
}

Errors

Errors are stable JSON objects with error.code, error.message, optional error.details, and request_id.

MCP Server

Connect Claude, Cursor, and other MCP clients to Wixma through the remote Streamable HTTP endpoint. The server uses browser authorization, so you do not paste API keys into Cursor.

{
  "mcpServers": {
    "wixma": {
      "url": "https://wixma.ai/mcp"
    }
  }
}

npx mcp-remote https://wixma.ai/mcp

Available MCP tools: wixma_upload_image, wixma_generate_image, wixma_edit_image, wixma_photographer, wixma_ai_filter, wixma_upscale_image, wixma_get_generation, wixma_list_generations, and wixma_get_credits. The MCP endpoint also answers standard ping health checks.

Input images are always passed as public HTTPS URLs. wixma_upload_image imports a URL once and returns a reusable upload_id; the generation tools also accept HTTPS URLs directly. Base64 and data URLs are rejected by design — writing image bytes into tool arguments makes MCP clients appear to hang. Wixma downloads the URL server-side, validates the real PNG/JPEG/WEBP bytes and dimensions, and rejects anything unusable before a provider job starts. The returned main_image can be passed directly to wixma_photographer, and the returned images array can be passed directly to wixma_edit_image.

When a generation is completed, wixma_get_generation returns the result both as a URL and as inline MCP image content, so clients like Claude render the finished image directly in the conversation.

wixma_ai_filter applies one of the curated Wixma AI filters (such as golden-backlight, blue-hour, polaroid, cinematic-still, noir-bw) to a photo. The professional prompts behind each filter are fixed and stay server-side; clients only choose a filter id.

// 1. Import an image from a public HTTPS URL
{
  "name": "wixma_upload_image",
  "arguments": {
    "url": "https://example.com/photo.jpg"
  }
}

// 2. Use the returned main_image
{
  "name": "wixma_photographer",
  "arguments": {
    "mode": "cloth_change",
    "main_image": { "upload_id": "upload_uuid_here" },
    "text_prompt": "elegant dark navy business suit",
    "quality": "medium",
    "aspect_ratio": "4:5"
  }
}

// Apply a curated AI filter (fixed, server-side prompt)
{
  "name": "wixma_ai_filter",
  "arguments": {
    "filter": "golden-backlight",
    "image": { "upload_id": "upload_uuid_here" },
    "quality": "medium"
  }
}

// Sequential edits: poll the first job, then use its generation id
{
  "name": "wixma_photographer",
  "arguments": {
    "mode": "location_change",
    "main_image": { "generation_id": "completed_generation_uuid" },
    "text_prompt": "ultra-realistic iPhone photo in a courtroom",
    "quality": "high",
    "aspect_ratio": "original"
  }
}