# Pixal3D API > Provider: **Pixal3D** > Source: https://www.pixazo.ai/models/pixal3d Pixal3D — generate a single GLB 3D model from a reference image. Backed by fal.ai's pixal3d endpoint. ## Pixal3D ### Image to Image (3D Models — Image to 3D) ## Base URL ``` https://gateway.pixazo.ai/pixal3d/v1 ``` ## Authentication All requests require an API key passed via header. Header Type Required Description Ocp-Apim-Subscription-Key string Yes Your API subscription key ## Pixal3D generate request ## Request Code HTTP Python JavaScript cURL ``` POST https://gateway.pixazo.ai/pixal3d/v1/pixal3d-request Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_API_KEY { "image_url": "https://example.com/example_inputs/dog.png", "resolution": 1024, "ss_guidance_strength": 7.5, "ss_guidance_rescale": 0.7, "ss_sampling_steps": 12, "ss_rescale_t": 5, "shape_slat_guidance_strength": 7.5, "shape_slat_guidance_rescale": 0.5, "shape_slat_sampling_steps": 12, "shape_slat_rescale_t": 3, "tex_slat_guidance_strength": 1, "tex_slat_sampling_steps": 12, "tex_slat_rescale_t": 3, "mesh_scale": 1, "max_num_tokens": 49152, "decimation_target": 200000, "texture_size": 2048, "remesh": true } ``` ``` import requests url = "https://gateway.pixazo.ai/pixal3d/v1/pixal3d-request" headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_API_KEY" } data = { "image_url": "https://example.com/example_inputs/dog.png", "resolution": 1024, "ss_guidance_strength": 7.5, "ss_guidance_rescale": 0.7, "ss_sampling_steps": 12, "ss_rescale_t": 5, "shape_slat_guidance_strength": 7.5, "shape_slat_guidance_rescale": 0.5, "shape_slat_sampling_steps": 12, "shape_slat_rescale_t": 3, "tex_slat_guidance_strength": 1, "tex_slat_sampling_steps": 12, "tex_slat_rescale_t": 3, "mesh_scale": 1, "max_num_tokens": 49152, "decimation_target": 200000, "texture_size": 2048, "remesh": true } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ``` const url = "https://gateway.pixazo.ai/pixal3d/v1/pixal3d-request"; const headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_API_KEY" }; const data = { "image_url": "https://example.com/example_inputs/dog.png", "resolution": 1024, "ss_guidance_strength": 7.5, "ss_guidance_rescale": 0.7, "ss_sampling_steps": 12, "ss_rescale_t": 5, "shape_slat_guidance_strength": 7.5, "shape_slat_guidance_rescale": 0.5, "shape_slat_sampling_steps": 12, "shape_slat_rescale_t": 3, "tex_slat_guidance_strength": 1, "tex_slat_sampling_steps": 12, "tex_slat_rescale_t": 3, "mesh_scale": 1, "max_num_tokens": 49152, "decimation_target": 200000, "texture_size": 2048, "remesh": true }; fetch(url, { method: "POST", headers: headers, body: JSON.stringify(data) }) .then(response => response.json()) .then(data => console.log(data)); ``` ``` curl -X POST "https://gateway.pixazo.ai/pixal3d/v1/pixal3d-request" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ --data-raw '{ "image_url": "https://example.com/example_inputs/dog.png", "resolution": 1024, "ss_guidance_strength": 7.5, "ss_guidance_rescale": 0.7, "ss_sampling_steps": 12, "ss_rescale_t": 5, "shape_slat_guidance_strength": 7.5, "shape_slat_guidance_rescale": 0.5, "shape_slat_sampling_steps": 12, "shape_slat_rescale_t": 3, "tex_slat_guidance_strength": 1, "tex_slat_sampling_steps": 12, "tex_slat_rescale_t": 3, "mesh_scale": 1, "max_num_tokens": 49152, "decimation_target": 200000, "texture_size": 2048, "remesh": true }' ``` ## Output ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "QUEUED", "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` [Try Now](https://api.pixazo.ai/api-details#api=pixal3d&operation=pixal3d-request) ## Webhook (Optional) Add the `X-Webhook-URL` header to your submit request to receive a `POST` callback when the job completes — no polling required. ### Webhook Headers Header Required Default Description `X-Webhook-URL` Yes (to enable) — HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed). `X-Webhook-Mode` No `terminal` `terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates. ### Example: enable webhook ``` X-Webhook-URL: https://your-server.com/webhook/callback X-Webhook-Mode: terminal ``` ### Callback Payload Your endpoint receives a `POST application/json` with the same shape as the `GET /v2/requests/status/{request_id}` response. Example terminal callback (mode `terminal`): ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "COMPLETED", "model_id": "pixal3d", "error": null, "output": { "media_url": [ "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.glb" ], "media_type": "model/glb" }, "created_at": "2026-05-22T13:17:32.110Z", "updated_at": "2026-05-22 13:19:23", "completed_at": "2026-05-22 13:19:23" } ``` ### Failure callback shape ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "ERROR", "model_id": "pixal3d", "error": "Description of the error", "output": null, "created_at": "...", "updated_at": "...", "completed_at": "..." } ``` ### Delivery semantics - **terminal mode (default)** — exactly one `POST` when the request reaches a terminal status. No callback during `PROCESSING`. - **sync mode** — `POST` on every status poll (with delay capped at ~15s) plus a final `POST` at terminal status. Use when you want progress updates. - **Idempotency** — use `request_id` as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates. - **Response** — respond `200 OK` within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries. - **HTTPS required** — plain `http://` URLs are rejected. ## Request Parameters - Pixal3D generate request Parameter Required Type Default Allowed values / range Description image\_url Yes string — — URL of the input image to convert to 3D. Must be publicly accessible. seed No integer — — Random seed for reproducibility. If omitted, a random seed is used. resolution No enum 1024 1024, 1536 Output resolution for initial structure generation. Higher values yield more detail but increase processing time. ss\_guidance\_strength No float 7.5 — How closely the initial 3D structure follows the input image. Higher values increase fidelity but may introduce artifacts. ss\_guidance\_rescale No float 0.7 — Dampens artifacts from high guidance in stage 1 (initial structure generation). ss\_sampling\_steps No integer 12 — Number of denoising steps for the initial 3D structure generation. ss\_rescale\_t No float 5 — Controls noise schedule sharpness for structure generation. Higher values emphasize early denoising stages. shape\_slat\_guidance\_strength No float 7.5 — How closely the detailed geometry follows the input image. Higher values preserve fine structural details. shape\_slat\_guidance\_rescale No float 0.5 — Dampens artifacts from high guidance in the shape refinement stage. shape\_slat\_sampling\_steps No integer 12 — Number of denoising steps for shape refinement. shape\_slat\_rescale\_t No float 3 — Controls noise schedule sharpness for shape refinement. Higher values prioritize early-stage noise reduction. tex\_slat\_guidance\_strength No float 1 — How closely the texture follows the input image colors. Lower values prevent color oversaturation. tex\_slat\_guidance\_rescale No float — — Dampens artifacts from high guidance in the texture generation stage. tex\_slat\_sampling\_steps No integer 12 — Number of denoising steps for texture generation. tex\_slat\_rescale\_t No float 3 — Controls noise schedule sharpness for texture generation. Higher values emphasize early denoising stages. mesh\_scale No float 1 — Scale factor applied to the inferred mesh. Values >1 enlarge the model, values <1 shrink it. max\_num\_tokens No integer 49152 — Maximum number of high-resolution tokens used by the cascaded shape sampler. Higher values improve detail at the cost of memory and time. decimation\_target No integer 200000 — Target number of vertices in the final mesh. Lower values reduce file size and improve performance. texture\_size No enum 2048 1024, 2048, 4096 Texture resolution baked onto the mesh. Higher values yield sharper textures but increase file size. remesh No boolean true — Rebuilds the mesh topology for cleaner, more uniform triangles. Disabling may preserve original topology but can result in irregular geometry. ## Example Request ``` { "image_url": "https://example.com/example_inputs/dog.png", "resolution": 1024, "ss_guidance_strength": 7.5, "ss_guidance_rescale": 0.7, "ss_sampling_steps": 12, "ss_rescale_t": 5, "shape_slat_guidance_strength": 7.5, "shape_slat_guidance_rescale": 0.5, "shape_slat_sampling_steps": 12, "shape_slat_rescale_t": 3, "tex_slat_guidance_strength": 1, "tex_slat_sampling_steps": 12, "tex_slat_rescale_t": 3, "mesh_scale": 1, "max_num_tokens": 49152, "decimation_target": 200000, "texture_size": 2048, "remesh": true } ``` ## Response ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "QUEUED", "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ## Request Headers Header Value Content-Type application/json Cache-Control no-cache Ocp-Apim-Subscription-Key YOUR\_API\_KEY ## Response Handling Common status codes. Code Meaning 202 Accepted — Request queued 400 Bad Request 401 Unauthorized 402 Insufficient Balance 403 Forbidden 429 Too Many Requests 500 Internal Server Error ## Error Responses Queue system errors and model validation errors. ### Queue System Errors ``` // 402 — Insufficient balance { "error": "Insufficient Balance", "message": "Your wallet does not have enough balance." } ``` ``` // 400 — Model not found { "error": "Model not found", "message": "Model 'pixal3d' not found or is disabled" } ``` ### Error via Status/Webhook ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "ERROR", "model_id": "pixal3d", "error": "Description of the error", "output": null } ``` ## Retrieving Results Poll the universal status endpoint to check progress and retrieve results. ### Endpoint ``` GET https://gateway.pixazo.ai/v2/requests/status/{request_id} Ocp-Apim-Subscription-Key: YOUR_API_KEY ``` ## cURL Example ``` curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ "https://gateway.pixazo.ai/v2/requests/status/pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ``` ## Response (Completed) ``` { "request_id": "pixal3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "COMPLETED", "model_id": "pixal3d", "error": null, "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixal3d_019dxxxx/output.glb"], "media_type": "model/glb" }, "created_at": "2026-03-31T10:00:00.000Z", "updated_at": "2026-03-31T10:00:15.000Z", "completed_at": "2026-03-31T10:00:15.000Z" } ``` ## Response Fields Field Type Description request\_id string Unique request identifier status string QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR model\_id string Model that processed the request error string|null Error message if failed output.media\_url array URLs to generated media (R2 CDN) output.media\_type string MIME type of the output created\_at string When request was created completed\_at string When request completed polling\_url string Status URL (initial response only) ## Status Values Status Description QUEUED Request accepted, waiting to be processed PROCESSING Being processed by the model COMPLETED Done — output contains the result FAILED Failed — check error field ERROR System error — not charged ## Status Flow ``` QUEUED → PROCESSING → COMPLETED → FAILED → ERROR ``` ## Typical Workflow 1. **Send a generate request** to the API endpoint 2. **Save the `request_id`** from the response 3. **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}` 4. **When `status` is `"COMPLETED"`**, download from `output.media_url` **Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.