Claude

Pixeloa

Pixeloa turns product photos into validated, true-to-scale 3D models and public AR pages (no app needed), plus QR codes and an embed snippet for the owner's website. You act on behalf of the account whose API key you were given, within that key's scopes.

Setup (once)

Prefer the MCP server: every Pixeloa operation is a tool, named exactly like the REST operationIds:

{ "mcpServers": { "pixeloa": { "type": "http", "url": "https://pixeloa.ai/mcp",
  "headers": { "Authorization": "Bearer pxk_live_…" } } } }

The owner creates the key in the Pixeloa dashboard: Account → API keys (choose scopes; optionally attach the key to an agent identity with a daily credit cap). No MCP? Call REST directly: https://pixeloa.ai/v1, same bearer header; schema at https://pixeloa.ai/openapi.json.

Procedure

Follow references/procedure.md exactly; it is the single source of truth (lifecycle order, when to confirm with the human, error handling, hard limits). Short form:

1. getMe: learn who you act as (actor), your scopes, spend_today, plan limits and usage.
2. createItem (title + 1–4 image URLs: public https, not on pixeloa.ai, first = front, photos already rotated) → item is analyzing.
3. Poll getItem until next_allowed_actions includes confirm_scale.
4. confirmScale in cm; prefer the owner's measurements; dimensions_cm.estimated is only a starting point.
5. startGeneration: spends credits; confirm with the owner unless clearly delegated. Poll getItem until model.available.
6. publishItem: changes public state; same rule. (unpublishItem reverses it, same rule.)
7. getItemLinks → AR URL, embed snippets, QR (generateItemQr if null). updateItem sets the buy-button product_url. Report back.

Inputs decide quality: 1–4 photos of the same object from different angles, JPG or PNG, first = front; a standardized-size object in frame helps sizing (list: https://pixeloa.ai/size-references). No measurements and no usable photos? Ask the owner first; see "Getting good inputs" in references/procedure.md for the fallbacks, including the last-resort human-task marketplace and the approval it needs.

Always send an idempotency_key on mutations (e.g. create-<sku>). Let next_allowed_actions drive you; never retry a step it does not list. A ready item is never regenerated in place; another result means a NEW item (charged again). Check item.publishable before publishItem.

Guardrails

• Never request or use a service-role key, another account's key, or a borrowed session.
• Never buy credits, change plans, delete accounts, or add webhook endpoints: human-only.
• deleteItem / deleteCatalog are irreversible: only when the owner explicitly asked for that deletion in this task.
• Stop on spend_cap_exceeded, plan_limit_reached, forbidden_scope, unauthorized; report the details, do not work around them.
• Never invent dimensions or publish what the owner did not ask to be public. Never reuse model files served for AR pages or embeds.

When something is off

Look up the current facts rather than guessing: references/live-docs.md lists the live URLs (docs, OpenAPI, capability descriptor, terms, trust page). Error table and marketplace guidance are in the procedure file. Quote request_id when reporting a 500 to support@pixeloa.ai.