PhotoCraft API
Turn a photograph into a Minecraft build made of blocks — from your own script, or from an AI agent you hand a key to.
Overview
The API does what the dashboard does: you send photos, we reconstruct a 3D model and convert it into a block map — a grid of Minecraft blocks the companion mod places in a world. Everything the site can do with a build, a key can do too.
Base URL https://photocraft.fun/api/v1 Auth Authorization: Bearer pc_live_… Spec https://photocraft.fun/api/v1/openapi.json Markdown https://photocraft.fun/api/v1/docs
The markdown version is written to be pasted into a prompt: it is the whole API on one page, small enough for an agent to hold in context.
Authentication
Every request carries an API key. Keys are minted in your profile — the quiet Enable API link under the token history opens the card. A key is shown once, at the moment it is created, and can be revoked at any time.
Authorization: Bearer pc_live_2crzIS95q0-oAhFVU2pDax99aujsdk…
The key is not the account password: it cannot change the account, and it cannot mint another key. Session cookies are not accepted here — /api/v1 is the machine surface.
Quickstart
Start a build. It answers immediately with an id, not with the finished build.
curl -X POST https://photocraft.fun/api/v1/generate \
-H "Authorization: Bearer $PHOTOCRAFT_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"images":[{"data":"<base64 of the photo>","media_type":"image/jpeg"}],
"scale":5,"name":"my_duck"}'202 {"buildId":"a1b2c3d4","status":"queued","position":1,
"poll_url":"/api/v1/builds/a1b2c3d4"}Then poll it until it is done — 60 to 120 seconds, so every few seconds is plenty.
curl https://photocraft.fun/api/v1/builds/a1b2c3d4 \ -H "Authorization: Bearer $PHOTOCRAFT_KEY"
{"buildId":"a1b2c3d4","status":"completed","totalBlocks":15180,
"previewImage":"<base64 PNG>","buildData":{…}}images takes one photo, or up to five of the same object from different angles (front, back, left, right, top) for a more accurate model — each base64 with no data: prefix, under 10 MB. scale is optional and defaults to 1. name accepts letters, digits, hyphens and underscores, must be unique on the account, and is what the player types in game: /photocraft build my_duck.
How it works
A build takes 60–120 seconds, so POST /generate answers 202 with a buildId and a poll_url. Poll GET /builds/{id} until status is completed; while it waits, position says how many builds are ahead of yours.
The token is reserved when the request is accepted and returned automatically if the build fails. An active plan is required — with an expired one every endpoint but /me answers subscription_required.
Scale 1 is roughly 20 blocks tall, scale 10 about 65. A rescale reuses the stored 3D model, so it takes ~15 seconds instead of a minute — but it costs a token too, and a build can exist at each scale only once.
Send Idempotency-Key on a POST and a retry replays the first answer instead of starting a second build and spending a second token. A failed attempt releases the key, so the same one can be used to send a fixed request.
60 requests per minute per key, and two builds waiting in the queue per account at a time.
Endpoints
/mePlan, tokens left, queue depth. The one endpoint an expired plan does not close./generateStart a build from one to five photos. Answers 202 with a build id to poll./buildsThe library, 75 per page, without previews. Takes page, search, sort and tags./builds/{id}One build: preview, stats, and the block map once it is completed. This is the polling endpoint./builds/{id}Rename it, or replace its colour tags./builds/{id}Deletes the build, the 3D model behind it and the photo it came from./builds/{id}/rescaleThe same object at another size, ~15 s. Answers with a NEW build id — poll that one./builds/{id}/refundAsk for the token back on a build that came out wrong. A person reviews it, usually within 3 hours.The block map
buildData is the result — the thing the mod places, and the thing you own.
dimensions {x, y, z} in blocks
palette one ASCII character per block type:
{"A": "minecraft:white_concrete"}
layers keyed by height, 0 at the bottom. Each string is a row
along X, one character per block, "." for empty.
totalBlocks how many blocks are placedSo layers["3"][7][2] is the block at x=2, y=3, z=7, and the palette says which Minecraft block that character is.
Errors
Every failure has the same shape. Branch on code, never on the message — the text may be reworded, the code will not.
{"error":{"code":"no_credits","message":"No credits remaining"}}| unauthorized | The key is missing, unknown or revoked |
| account_blocked | The account is blocked |
| api_disabled | API access is switched off for this account |
| subscription_required | The plan has expired — every endpoint but /me answers this |
| no_credits | No tokens left |
| no_images | No photo in the request |
| too_many_images | More than five photos |
| invalid_image | An entry carries no base64 in data |
| image_too_large | A photo is over 10 MB |
| invalid_scale | Scale outside 1–10 |
| invalid_name | Name has characters other than A-Z a-z 0-9 _ - |
| name_taken | That name already exists on the account |
| invalid_tags | Tags is not an array of colour names |
| nothing_to_update | A PATCH with neither name nor tags |
| not_found | No such build on this account |
| no_model | That build has no 3D model to rescale |
| scale_exists | This build already exists at that scale |
| model_gone | The source model is no longer stored |
| refund_pending | A refund is already open for this build |
| already_refunded | This build was refunded before |
| not_refundable | The build failed or is unfinished — a failed build's token comes back on its own |
| idempotency_in_flight | The first request with this key is still running |
| too_many_queued | Two builds are already waiting; wait for one |
| queue_full | The service is saturated — retry in a minute |
| rate_limited | Over 60 requests in a minute |
| internal | Our fault — retry |
The same documentation as markdown, sized to paste into a prompt — plus the OpenAPI spec if your tooling reads one.
PHOTOCRAFT IS NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG, 4J STUDIOS, MICROSOFT, SONY OR NINTENDO.