Suzanne
Sign inGet started
Browse docs

POST /v1/generations/photo-to-3d

Submit 1–4 photos and get back a job_id. Single-photo and multi-view auto-route to the right vendor.

Submit a photo → 3D job.

Two ways to provide images, pick exactly one:

A. Upload-then-reference (recommended, supports up to 4 views)

{
  "model": "sculptor",
  "images_upload_ids": {
    "front": "upl_<uuid>",
    "back":  "upl_<uuid>",
    "left":  "upl_<uuid>",
    "right": "upl_<uuid>"
  },
  "params": { "faces": 100000, "pbr": true },
  "outputs": ["glb"]
}
  • front is required; back / left / right are optional.
  • Send 1 view → single-image model. Send 2–4 → multi-view model. Auto-routed.
  • Get upl_* ids by calling POST /v1/uploads.

B. Inline base64 (single-photo only, ≤ ~5 MB)

{
  "model": "sculptor",
  "images_inline": { "front": "<base64-jpeg-or-png>" },
  "params": { "pbr": true },
  "outputs": ["glb"]
}

⚠ Multi-view inline is not supported. Sending more than front via images_inline returns 400 inline_multi_photo_not_supported. Use the upload-then-reference path for multi-view jobs.

Response: 202 Accepted

{
  "job_id": "job_<uuid>",
  "status": "queued",
  "created_at": "2026-06-01T07:09:15.595749Z",
  "billable_amount_cents": 0
}

Then poll GET /v1/jobs/{job_id} until the job is terminal.

Curl: multi-view from 4 uploads

KEY="sk_test_xxx"
BASE="https://api.suzanne3d.com"
 
curl -sS -X POST "$BASE/v1/generations/photo-to-3d" \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "sculptor",
    "images_upload_ids": {
      "front": "upl_aaa",
      "back":  "upl_bbb",
      "left":  "upl_ccc",
      "right": "upl_ddd"
    },
    "params": { "faces": 100000, "pbr": true },
    "outputs": ["glb"]
  }'

Errors

HTTPcodeMeaning
400validation_errorRequest body doesn't match the schema.
400inline_multi_photo_not_supportedMulti-view inline isn't supported; use images_upload_ids.
400invalid_paramfaces value not in the allowed enum.
401unauthorizedMissing / bad API key.
409concurrent_limit_reachedAccount is at the concurrent-jobs ceiling.

When a job ends with status: "failed", expect error.code of missing_image, insufficient_views, or one of the vendor_* codes. See the full Error Reference.