Create a 3D model
Turn a sentence into a textured 3D model you can drop into a viewer, a scene or a game engine.
- MCP tool
- create_3d_model
- MCP endpoint
- /mcp/3d
- REST
- POST /v1/tools/create_3d_model/jobs
- Price
- From 50 credits
Overview
Describe one object and get back a self-contained glTF binary with textures, pictures of the finished model from six sides, the picture it was made from, and a provenance file that records exactly how it was made. Choose economy for a compact model in minutes, high for full detail, or max: high plus an extra geometry refinement pass for finer surface detail; takes longer. Geometry is unitless: no physical size, rigging, watertightness or print readiness is inferred from a description.
- Input
- A description of up to 4,000 characters; no file
- Outputs
- model.glb, model.web.glb, model_preview.png, six single views, model_views.json, reference.png and generation.json
- Quality
- economy: about 120,000 faces, 1024 × 1024 PBR textures · high: 2048 × 2048 textures, about one million faces · max: high plus an extra geometry refinement pass for finer surface detail; takes longer
- Duration
- Asynchronous; one-hour deadline including queueing and execution
Quickstart
Send the options as JSON. 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/jobs \
-H "Authorization: Bearer $MCPBYTES_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"options": {
"description": "a fierce dragon statue carved from dark green jade, coiled on a rough stone base with its wings folded and its jaws open, polished highlights on the scales",
"quality": "high",
"seed": 7
},
"idempotency_key": "model-example-001"
}'{
"tool": "create_3d_model",
"status": "queued",
"input_kind": "parameters",
"options": {
"description": "a fierce dragon statue carved from dark green jade, coiled on a rough stone base with its wings folded and its jaws open, polished highlights on the scales",
"quality": "high",
"texture_resolution": 2048,
"seed": 7
},
"workflow": {
"deadline": "2026-11-01T06:25:11.141Z",
"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",
"status": "succeeded",
"compute_ms": 157031,
"result": {
"files": [
{
"name": "reference.png",
"bytes": 521500,
"content_type": "image/png",
"url": "https://api.mcpbytes.com/blob/dl/…"
},
{
"name": "model.glb",
"bytes": 45471344,
"content_type": "model/gltf-binary",
"url": "https://api.mcpbytes.com/blob/dl/…"
},
{
"name": "generation.json",
"bytes": 6876,
"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.
Input
No file. Send the options in a JSON body, {"options": {…}}, or as arguments of the MCP tool. Keep private text such as prompts out of URLs.
idempotency_key is required. Repeating a request with the same key returns the original job instead of starting and charging a new one; reusing a key for a different request returns 409 idempotency_conflict.Options
Put options in the options object of the JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.
- description
text, up to 4000 charactersThe object to create. Required.- quality
economy · high · maxThe reconstruction profile. Max is high plus an extra geometry refinement pass for finer surface detail; it takes longer. Default economy.- texture_resolution
1024 · 2048Texture size in pixels, fixed by the quality profile (1024 for economy, 2048 for high and max).- target_faces
100000 · 300000 · 1000000High and max quality only: how many faces to keep before textures are baked. Default 1000000; lower values give lighter models with matching textures.- seed
integer 0 – 4294967295Reproducible seed within the same profile versions. Random when omitted.
Outputs
A succeeded job lists its files in result.files, each with a download url.
- model.glb
- Self-contained glTF binary: one mesh, PBR material with base colour and metal/roughness textures, opaque rendering.
- model.web.glb
- The same model for browsers and engines: Draco-compressed geometry and WebP textures; size depends on the asset. Every face and the full texture resolution are kept.
- model_preview.png
- The finished model.glb rendered from the front, back, left, right, top and bottom on one labeled sheet; MCP clients also receive it as an image with the job.
- model_front.png … model_bottom.png
- Each of the six views on its own, 512 × 512: model_front, model_back, model_left, model_right, model_top and model_bottom.
- model_views.json
- Each view's file, camera (position, target, up) and framing bounds, with the SHA-256 of the model.glb they were rendered from.
- reference.png
- The generated source image the model was built from (1024 × 1024 RGBA on a transparent background), not a render of the finished model.
- generation.json
- Provenance: your options, image digests and model revisions, seeds, effective settings, validation counts and timings.
Download links last up to 24 hours, capped by output retention; read the job again for fresh links. The model is a best-effort interpretation of the description: sides the picture does not show are invented, dimensions are not physical, and materials use opaque rendering. The views are orthographic with +Y up and show the model as it is, flaws included; the front view looks at the model's +Z side, whichever way the object itself faces.
Tips
- Describe one object with its materials and colours. Avoid scenes and text.
- Send the description in the JSON body or as MCP arguments, never in a URL.
- Hidden sides are invented, and geometry is unitless: no physical size, rigging, watertightness or print readiness is inferred.
- 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.
MCP
Your agent calls create_3d_model. Connect it to https://api.mcpbytes.com/mcp/3d for this tool and the rest of its family (Create a game asset, Create a 3D model from an image, Optimize a 3D model, Simplify a 3D model, Rig a 3D model, Animate a 3D model, Split a 3D model into parts, Inspect a 3D model), or to https://api.mcpbytes.com/mcp for every tool.
Claude CodeOAuth or API key
The first form signs in through the browser when you run /mcp. In .mcp.json (project root), ${MCPBYTES_API_KEY} is read from the environment when Claude Code connects. Claude Code docs
claude mcp add --transport http mcpbytes \
https://api.mcpbytes.com/mcp/3dCodex (CLI, IDE extension, ChatGPT desktop)OAuth or API key
Codex reads the key from the environment variable each time it connects. The same table can go in ~/.codex/config.toml by hand; codex mcp add has no --header flag. Codex docs
codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/3d \
--bearer-token-env-var MCPBYTES_API_KEYCursorOAuth or API key
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Remote servers take no "type". Without the header, the client signs you in with GitHub or an email link (OAuth). Cursor docs
{
"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:
- wait_seconds
0–45, default 0How long the call waits for the result. If the job is still running, the agent calls get_job.- idempotency_key
RequiredReuse it with the same arguments when retrying after a network error.
What the agent sees
- create_3d_model
- Create a textured 3D model from a description. Returns model.glb, model.web.glb (Draco + WebP, for browsers and engines), model_preview.png (the finished model rendered from six sides on one labeled sheet; get_job also returns it as an image), model_{front,back,left,right,top,bottom}.png (each view alone), model_views.json (each view's camera and the SHA-256 of model.glb), reference.png (the generated source image the model was built from, not a render of it) and generation.json. This is an asynchronous job; use get_job to follow progress. A failed job is refunded. quality: economy, texture_resolution: 1024: 50 credits. quality: high, texture_resolution: 2048: 75 credits. quality: max, texture_resolution: 2048: 150 credits. Requires idempotency_key; retain it when retrying the same request.
- create_upload
- Returns a one-hour URL to PUT a local file to; then call the tool with the upload_id.
- get_job
- Status and results of a job; waits up to wait_seconds for it to finish.
- cancel_job
- Cancel a queued job or a workflow whose can_cancel is true; repeated calls never delete results.
- list_jobs
- Your most recent jobs, newest first.
- read_job_file
- Reads a text output (.txt .json .md .csv) of a succeeded job in chunks.
Setup for every client, and how agents upload files and read results: Connect over MCP.
Agent skill
The MCPBytes skill teaches agents this tool, in references/create_3d_model.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:
printf '{"description": "a wooden rocking horse",
"quality": "economy"}' > options.json
python scripts/mcpbytes.py run create_3d_model \
--options-json options.json --out model/
python scripts/mcpbytes.py job j_...Pricing
From 50 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.
- Economy · 1024 px textures
- 50 credits
- High · 2048 px textures
- 75 credits
- Max · 2048 px textures
- 150 credits
One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.
Limits
By account
- Jobs at once
- Free3 jobs
- Pay as you go5 jobs
- Monthly bundle8 jobs
- Results kept
- Free1 day
- Pay as you go7 days
- Monthly bundle30 days
- Description
- Up to 4,000 characters
Free until the first purchase, Pay as you go after any credit pack, Monthly bundle while one is active. GPU tools, this one included, run up to 5 of an account's jobs at a time; the rest wait their turn. GET /v1/me returns your tier (plan), your limits and current usage; Limits & errors explains what happens when one is reached.
Errors
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.
- invalid_image
- The generated reference had no usable foreground for reconstruction. Any charge is refunded.
- invalid_output
- An output failed validation (missing alpha, empty geometry, missing texture or oversized file). Any charge is refunded.
- out_of_memory
- The generation needed more memory than its profile allows; try a simpler description.
- timeout
- The job did not finish within its deadline. Any charge is refunded.
- capacity_exhausted
- Budget exhausted: HTTP 503 at creation, or a failed job if the budget ran out before charging. Try again later.
- unsupported_format
- The tool does not take this file type.
- insufficient_credits
- The job costs more than the balance, which is known once the input has been measured. Nothing was charged.
Requests can also fail before a job starts, with an HTTP status: see HTTP errors.