API reference

Generate textured 3D models from your own code. JSON over HTTPS, one header for auth.

Base URL: https://meshforgeai.com/api/v1. Generation is asynchronous: you create a generation, then poll it or stream its progress until it reaches a terminal status.

Authentication

Create a key under Settings → API keys. Keys look like mf_live_… and are shown once — we store only a hash. Send the key in the X-API-Key header on every request. Revoked keys and keys of suspended accounts are rejected.

Check your key
curl https://meshforgeai.com/api/v1/me \
  -H "X-API-Key: $MESHFORGE_API_KEY"

Create a generation

POST/api/v1/generations

Holds the quoted credits immediately and queues the job. When it succeeds you are charged what the provider actually used (never more than the quote; the difference comes back automatically); a failed generation is refunded in full. Costs: text 5 (no texture) / 10 (textured); image 15; low-poly 20; +5 for HD (4K) textures, +10 for 8K textures, +10 for ULTRA geometry, +3 for the T-pose pre-step, +3 per extra export format.

FieldTypeDescription
type"text" | "image"Required.
promptstringRequired for text. 3–1024 characters.
image_urlstring (URL)Required for image. Public http(s) URL to a JPEG, PNG or WebP up to 10 MB. Downloaded by our worker; if it cannot be fetched the generation fails and is refunded.
options.model"STANDARD" | "LOWPOLY" | "LOWPOLY_PRO"Default STANDARD. LOWPOLY = game-ready low poly, LOWPOLY_PRO = low poly with quad support (preview).
options.quality"FAST" | "STANDARD" | "ULTRA"Default STANDARD. ULTRA = detailed geometry (STANDARD model only); FAST = fast texturing.
options.texture"NONE" | "STANDARD" | "PBR"Default STANDARD.
options.texture_quality"STANDARD" | "HD" | "EXTREME"Default STANDARD. HD = 4K maps, EXTREME = 8K maps. Ignored when texture is NONE.
options.texture_4kbooleanDeprecated alias of texture_quality HD.
options.polycountintegerTarget triangle count, 500–2,000,000 (above 1,500,000 only with ULTRA; low-poly models cap lower). Omit for adaptive.
options.quadbooleanDefault false. Quad topology; the model is delivered as FBX.
options.smart_low_polybooleanDefault false. Hand-crafted style low poly (STANDARD model), up to 20,000 faces.
options.seedintegerOptional. Same seed and same input give the same mesh.
options.formatsarrayAny of GLB FBX OBJ USDZ STL. Default ["GLB"].
options.negative_promptstringText only, up to 255 characters.
options.t_posebooleanImage only. Default false. Reposes the subject into a T-pose before modelling (helps rigging).
options.remove_backgroundbooleanAccepted for compatibility and ignored: the subject is isolated automatically.
options.parent_asset_idstringRemix: an asset you own or a public one.
Text to 3D
curl -X POST https://meshforgeai.com/api/v1/generations \
  -H "X-API-Key: $MESHFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "prompt": "a weathered bronze viking helmet with horns",
    "options": { "texture": "PBR", "formats": ["GLB", "USDZ"] }
  }'
Image to 3D
curl -X POST https://meshforgeai.com/api/v1/generations \
  -H "X-API-Key: $MESHFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "image", "image_url": "https://example.com/chair.png" }'
202 Accepted
{ "id": "cmf0x8k2p0001l50g7h3d9q2a", "status": "QUEUED", "credits_charged": 15, "credits_remaining": 485 }

Get a generation

GET/api/v1/generations/:id

status is one of QUEUED RUNNING SUCCEEDED FAILED CANCELED. type is one of text image multiview texture retopology rig animate convert (studio steps appear here too). When it is SUCCEEDED, files holds signed download URLs valid for one hour — request the generation again for fresh ones.

Request
curl https://meshforgeai.com/api/v1/generations/cmf0x8k2p0001l50g7h3d9q2a \
  -H "X-API-Key: $MESHFORGE_API_KEY"
200 OK
{
  "id": "cmf0x8k2p0001l50g7h3d9q2a",
  "type": "text",
  "status": "SUCCEEDED",
  "progress": 100,
  "error": null,
  "credits_charged": 15,
  "created_at": "2026-09-21T10:00:00.000Z",
  "started_at": "2026-09-21T10:00:01.000Z",
  "finished_at": "2026-09-21T10:01:32.000Z",
  "asset": { "id": "…", "slug": "a-weathered-bronze-viking-helmet-9q2a0b1c", "title": "A weathered bronze viking helmet with horns", "thumbnail_url": "https://…" },
  "files": [
    { "format": "GLB", "bytes": 4812201, "url": "https://…", "expires_at": "2026-09-21T11:05:00.000Z" }
  ]
}

Stream progress (SSE)

GET/api/v1/generations/:id/stream

A text/event-stream. The current state is sent immediately, then every change. Each event is a single data: line with JSON; lines starting with : are heartbeats sent every 15 seconds. The server closes the stream once the status is terminal. Opening a stream counts as one request against your rate limit.

Request
curl -N https://meshforgeai.com/api/v1/generations/cmf0x8k2p0001l50g7h3d9q2a/stream \
  -H "X-API-Key: $MESHFORGE_API_KEY"
Events
data: {"jobId":"cmf0x8k2p0001l50g7h3d9q2a","status":"RUNNING","progress":42,"assetId":null,"error":null}

: ping

data: {"jobId":"cmf0x8k2p0001l50g7h3d9q2a","status":"SUCCEEDED","progress":100,"assetId":"cmf0x9…"}
FieldTypeDescription
jobIdstringThe generation id.
statusstringQUEUED | RUNNING | SUCCEEDED | FAILED | CANCELED
progressinteger0–100.
assetIdstring | nullSet on SUCCEEDED.
errorstring | nullHuman-readable reason on FAILED.

Account

GET/api/v1/me

Request
curl https://meshforgeai.com/api/v1/me -H "X-API-Key: $MESHFORGE_API_KEY"
200 OK
{ "id": "…", "email": "you@example.com", "plan": "PRO", "credits": 475, "max_active_jobs": 3, "active_jobs": 1 }

Rate limits

Each key may make 60 requests per minute (sliding window). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Over the limit you get 429 with a Retry-After header in seconds. Separately, your plan caps how many generations can be queued or running at once (max_active_jobs in /me).

Errors

Every error has the same shape:

{ "error": { "code": "insufficient_credits", "message": "This generation costs 25 credits." } }

Error codes are stable. The message field is always in English, whatever language this site is shown in.

CodeHTTP statusDescription
invalid_request400Body or parameters failed validation. The message names the field.
unauthorized401Missing, malformed or revoked X-API-Key.
insufficient_credits402Not enough credits for this generation.
forbidden403Account suspended, or the resource is not yours.
not_found404No such generation (or endpoint).
too_many_active_jobs409Your plan’s concurrent-generation cap is reached. Wait for one to finish.
rate_limited429Over 60 requests/minute. See Retry-After.
internal_error500Our side. Safe to retry.