Idol 1 API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Callback Payload (success)

{
  "request_id": "idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "idol",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.ply"
    ],
    "media_type": "model/ply"
  },
  "created_at": "2026-11-11T12:56:10.571Z",
  "updated_at": "2026-11-11 12:56:38",
  "completed_at": "2026-11-11 12:56:37"
}

Failure callback shape

{
  "request_id": "idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "idol",
  "error": "Generation failed: the request was rejected (image_url: Failed to load the image. Please ensure the image file is not corrupted and is in a supported format).",
  "output": null,
  "created_at": "2026-11-11T12:58:51.848Z",
  "updated_at": "2026-11-11 12:59:00",
  "completed_at": "2026-11-11 12:59:00"
}

Callbacks are idempotent on request_id — de-duplicate on it. Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

How usage is measured

Billed per 3D object: one per request, at the same rate whatever num_inference_steps or num_gaussians. The rate is in the pricing panel on this page. Nothing is charged for a request that fails.

Parameters not supported

Rejected with 400

Checked when you submit: the request is rejected before it is queued.

Accepted, then the request fails

These pass the submit check, so the submit returns 202, but the request then fails with status: "ERROR". Nothing is charged.

Accepted but ignored

Any other parameter is dropped and has no effect.

The output file

output.media_url is one .ply file (model/ply): a standard 3D Gaussian splatting (3DGS) PLY, binary_little_endian 1.0, with one vertex per Gaussian and 17 properties each: x, y, z, nx, ny, nz, f_dc_0, f_dc_1, f_dc_2, opacity, scale_0, scale_1, scale_2, rot_0, rot_1, rot_2, rot_3.

Open it in any Gaussian splat viewer or editor, for example SuperSplat, or load it with the splat loaders for three.js and Babylon.js. A splat is not a mesh: it renders photoreal in splat viewers, but it has no polygons, so tools that need a mesh (3D printing, CAD, most game-engine imports) need a conversion step first. The object is centered, and the side the image did not show is generated.

Input tips

Timing

A splat at the defaults took about 30 seconds from submit to result at launch, and one at the maximum num_gaussians about 45 seconds. Polling the status endpoint every 3 to 5 seconds is enough, or use a Webhook.

Request Headers

Response Handling

Error Responses

A 400 names every rejected parameter in violations. This one was sent {"image_type": "photo", "steps": 10} with an image:

{
  "error": "Invalid request parameters",
  "message": "'image_type' must be one of: \"synthetic\", \"real\" (got \"photo\"); 'steps' is not a parameter here: use 'num_inference_steps' (1 to 50).",
  "violations": [
    "'image_type' must be one of: \"synthetic\", \"real\" (got \"photo\")",
    "'steps' is not a parameter here: use 'num_inference_steps' (1 to 50)."
  ]
}

An image_url that cannot be downloaded is also a 400, with the reason under failures:

{
  "request_id": "idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "error": "Asset proxy failed",
  "message": "Failed to proxy asset https://raw.githubusercontent.com/speridlabs/idol-sdk/main/no-such-image.png: 404 Not Found",
  "failures": [
    {
      "url": "https://raw.githubusercontent.com/speridlabs/idol-sdk/main/no-such-image.png",
      "error": "404 Not Found"
    }
  ]
}

Retrieving Results

Poll the status endpoint with the request_id until status is COMPLETED or ERROR, then download the splat from output.media_url.

curl 'https://gateway.pixazo.ai/v2/requests/status/idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

Captured from a real Idol request at launch; the request id is masked.

{
  "request_id": "idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "idol",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/idol_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.ply"
    ],
    "media_type": "model/ply"
  },
  "created_at": "2026-11-11T12:56:10.571Z",
  "updated_at": "2026-11-11 12:56:38",
  "completed_at": "2026-11-11 12:56:37"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure). Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.