Generation status

A real generation takes longer than a proxy will hold a request open, so the working pattern is two calls: POST /api/generate/start hands you a jobId, and GET /api/generate/status?jobId= tells you where it got to. When the job finishes, its result field is the complete /api/generate response body, model URL included.

Start a job#

The raw body and content type are captured and replayed against the generation pipeline in the background, so both the JSON text form and the multipart image form work unchanged. See /docs/api/generate for the fields. An empty body is 400 invalid body.

{ "jobId": "job_m2k1r8q_4f7a9c2e", "status": "queued" }

Poll it#

{
  "id": "job_m2k1r8q_4f7a9c2e",
  "userEmail": "[email protected]",
  "status": "done",
  "createdAt": 1757404800000,
  "startedAt": 1757404800412,
  "completedAt": 1757404838907,
  "result": { "modelUrl": "gs://…", "printStatus": "ready", "creditsCharged": 1, "…": "…" }
}

The three timestamps are epoch milliseconds. startedAt, completedAt, result and error are only present once they apply.

error carries the message the generation route returned — an engine failure, a moderation refusal, a no_credits rejection — or "Generation was interrupted and did not finish." for a job swept after 30 minutes.

A polling loop#

JOB=$(curl -s https://x3dstudios.com/api/generate/start \
  -H "Authorization: Bearer $X3D_EXT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"a low-poly owl figurine","mode":"fast_draft"}' | jq -r .jobId)

while :; do
  BODY=$(curl -s "https://x3dstudios.com/api/generate/status?jobId=$JOB" \
    -H "Authorization: Bearer $X3D_EXT_TOKEN")
  case "$(echo "$BODY" | jq -r .status)" in
    done)  echo "$BODY" | jq -r '.result.modelUrl, .result.printStatus'; break ;;
    error) echo "$BODY" | jq -r .error; exit 1 ;;
  esac
  sleep 5
done

Five seconds is a sensible interval. Status reads are not rate-limited, but nothing changes faster than the pipeline's own two-second engine poll, and a text draft rarely finishes in under twenty seconds.

Getting the model#

result.modelUrl is a gs:// object URI in our storage, not a public link. Fetch it through the proxy, which checks that the signed-in account owns that generation.

curl -G "https://x3dstudios.com/api/model-proxy" \
  --data-urlencode "url=$MODEL_URL" \
  --data-urlencode "download=true" \
  -b "$COOKIE_JAR" -o model.glb

Is anything running?#

Session cookie only — this one has no extension-token support. It never returns 401: signed out gives 200 {"active":false}. Signed in with a live job gives {"active":true,"jobId","status","createdAt"}. Jobs older than 30 minutes are ignored here, so a job orphaned by a lost instance cannot block the account forever.

Errors#