Create a 3D model from an image

Send one image of an object and get back a self-contained glTF binary with PBR textures, plus a generation.json that records the exact image digest, model revision, seeds, settings and validation counts. Economy uses a roughly 40,000-face paint budget and 1K textures; high offers a configurable face target and 2K textures. Start the job, keep its id and poll. Geometry is unitless: no physical size, rigging, watertightness or print readiness is inferred from a picture.

Formats

.png .jpg .jpeg, up to 20 MB and 25 megapixels

Outputs

model.glb, model.web.glb and generation.json

Quality

economy: about 40,000 faces, 1024 × 1024 PBR textures · high: 2048 × 2048 textures, about one million faces after decimation

Background

Transparent PNGs are used as-is; opaque images are segmented first

Duration

Asynchronous; one-hour deadline including queueing and execution

Send the file as the request body with the options in the query string, or refer to it in a JSON body (upload_id or url) with an options object. The response is the new job; poll it until its status is final, then download the files in result.files.

# idempotency_key is required: repeating the same request returns the same job
curl https://api.mcpbytes.com/v1/tools/create_3d_model_from_image/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mcpbytes.com/showcase/photo-t.png",
    "options": {"quality": "high", "seed": 42},
    "idempotency_key": "image-example-001"
  }'

{
  "tool": "create_3d_model_from_image",
  "status": "queued",
  "input_kind": "file",
  "options": {
    "quality": "high",
    "texture_resolution": 2048,
    "seed": 42
  },
  "workflow": {
    "stage": "Modeling",
    "deadline": "2026-09-22T00:58:46.412Z",
    "cancel_pending": false,
    "refund_pending": false
  },
  "capabilities": {
    "can_cancel": true
  },
  "result": null
}

# JOB_ID is the id from the create response; poll until status is final
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

# Once status is succeeded, download the model from result.files[].url
curl -fsSLo model.glb "$MODEL_URL"

{
  "tool": "create_3d_model_from_image",
  "status": "succeeded",
  "credits_charged": 100,
  "compute_ms": 196488,
  "result": {
    "files": [
      {
        "name": "model.glb",
        "bytes": 48154080,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "generation.json",
        "bytes": 1694,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ]
  }
}

Jobs of this tool take minutes. While one runs, workflow.stage says what is happening and workflow.deadline when it must finish. Cancel it with POST /v1/jobs/{id}/cancel while capabilities.can_cancel is true.

More on statuses, downloads and retention in Jobs & files.

One file per job, in one of these ways. The formats it accepts are listed in the overview.

# 1. Create an upload URL (valid for one hour)
curl https://api.mcpbytes.com/v1/uploads \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "T.png"}'

# 2. PUT the file to the "url" from the response
curl -X PUT --data-binary @T.png "$UPLOAD_URL"

# 3. Start the job with the "upload_id"
curl https://api.mcpbytes.com/v1/tools/create_3d_model_from_image/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\",
    \"options\": {
      \"quality\": \"economy\"
    },
    \"idempotency_key\": \"create_3d_model_from_image-upload-001\"
  }"

Put options in the query string when the file is the request body, in the options object of a JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

Download links last up to 24 hours, capped by output retention; read the job again for fresh links. The mesh is a best-effort reconstruction of what the image shows: hidden sides are invented, dimensions are not physical, and materials use opaque rendering even where the texture has alpha.

• One object on a transparent background gives the cleanest silhouette. Opaque images are cut out first.
• Hidden sides are invented, and geometry is unitless: no physical size, rigging, watertightness or print readiness is inferred from a picture.
• Pass image.png of a create_image job as job_file. Its reference_3d preset frames one isolated object from a three-quarter view.
• A job takes minutes: keep its id and poll get_job. Repeating the request with the same idempotency key returns the same job instead of a new charge.

Your agent calls create_3d_model_from_image. Connect it to https://api.mcpbytes.com/mcp/3d for this tool and the rest of its family (Create a 3D model, Optimize a 3D model, Simplify a 3D model, Split a 3D model into parts, Inspect a 3D model), or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/3d

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/3d \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/3d",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/create_3d_model_from_image.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

python scripts/mcpbytes.py run create_3d_model_from_image \
  photo.png -o quality=economy --out model/
# Or an earlier job's output, without downloading it
python scripts/mcpbytes.py run create_3d_model_from_image \
  --job-file j_... image.png --no-wait
python scripts/mcpbytes.py job j_...

From 30 credits. The selected option's price is charged before paid processing starts, and a canceled job is refunded. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Create an imageGenerate the picture first, then pass its image.png as job_file.create_image
• Optimize a 3D modelRebuild model.glb at a lower triangle count: pass it as job_file.optimize_3d_model
• Split a 3D model into partsSplit the model into parts: download model.glb and upload it.split_3d_model