Developers

MCP server

Streamable HTTP, with OAuth 2.1: client-ID metadata documents or dynamic registration, PKCE (S256), discovery at /.well-known/oauth-protected-resource/mcp. The person signs in to Photo2Skin and allows your app once; they can disconnect it in Settings. Paid tools return a job id within seconds — poll get_job — and take an idempotency_key, so a retry is never charged twice.

# 1. Start a skin (returns at once)
create_skin { "description": "a knight in gold armour", "idempotency_key": "knight-1" }
→ { "job_id": "skin_…", "status": "generating" }

# 2. Poll until it's done (30–90 s); the skin comes back as an image
get_job { "job_id": "skin_…" }
→ { "status": "done", "model": "classic", "download_url": "https://…" }

# 3. Change it in words (a new skin; the first is kept)
create_skin { "job_id": "skin_…", "description": "add a red cape" }
→ { "job_id": "skin_…", "status": "generating" }

# Or edit a real skin they already have: bring it in first
save_skin { "player": "Notch" }   → { "job_id": "skin_…" }

# Some skins come in several takes: get_job says "takes": 2 and shows them
choose_skin_take { "job_id": "skin_…", "take": 2 }

# Builds work the same way, and take minutes
create_build { "description": "a lighthouse on a cliff", "size": 64, "quality": "high" }
→ { "job_id": "build_…", "status": "generating" }
get_job { "job_id": "build_…" }
→ { "status": "done", "block_count": 19630, "builder_url": "https://…/ai-builder?build=…" }

Install steps for each app are on the AI agents page. A ready-made skill for Claude Code and Codex: SKILL.md.

Public API (no account)

Read-only and free. Schema: https://app.photo2skin.com/api/openapi.json. Please keep it under a request a second and cache what you can.

• GET https://app.photo2skin.com/api/library/skins?q=knight&page=1

  Search the skin library

• GET https://app.photo2skin.com/api/library/skins/{id}

  One skin: name, tags, model, stats

• GET https://app.photo2skin.com/api/library/skins/{id}/skin.png

  The 64x64 skin PNG

• GET https://app.photo2skin.com/api/library/grab/{username}

  The skin a Java player is wearing now

• GET https://app.photo2skin.com/api/posts?kind=build&q=castle

  Search the library of AI builds

• GET https://app.photo2skin.com/api/credit-costs

  What each creation costs, in credits

Rules

Never spend a person’s credits without their say-so, and never try to buy for them — send them to the pricing page. Skins in the library belong to their creators; link to their pages. Security reports: [email protected].