# AI3D API v2 model: idol-fal

Generate a Gaussian-splat object from one image with Sperid Labs Idol on fal.ai.

- AI3D model ID: `idol-fal`
- Task: `image_to_3d`
- AI3D provider adapter: `fal` (`speridlabs/idol`)
- Related models: `idol` is the general route. It sends a job to `idol-hf` (the Hugging Face Space) by default, and here while that Space has a job in flight. Submit to `idol-fal` directly to always use fal.
- Availability: Check `GET https://api.ai3d.dev/v2/models` before use; deployment configuration and key model allowlists can affect access.
- Shared implementation guide: <https://api.ai3d.dev/v2/llms.txt>
- AI3D API reference: <https://api.ai3d.dev/v2/openapi.json>

## Request

Use the AI3D v2 job API. Do not call the provider directly or put provider credentials in the client.

- Method and URL: `POST https://api.ai3d.dev/v2/jobs`
- Authentication: `Authorization: Bearer <AI3D_API_KEY>` with write permission and this model allowed on the key.
- Content type: `application/json`
- Source: a publicly reachable HTTPS image of a single object in `image_url`. Upload PNG, JPEG, or WebP up to 10 MiB with `POST /v2/uploads` and pass the returned signed `image_url` if needed.
- Price: fal's live price for this endpoint (listed at $0.10 per generation when this guide was written). Check `/v2/billing/prices` for the current reservation; final usage can differ from the estimate.
- Request settings: `input` may be omitted or contain only the fields below; the API supplies these defaults:

```json
{
  "image_type": "synthetic",
  "num_gaussians": 262144,
  "num_inference_steps": 50,
  "guidance_scale": 3,
  "enable_safety_checker": true
}
```

Accepted settings:

- `image_type`: `synthetic` for renders and generated images (tight crop) or `real` for photographs (looser crop).
- `num_gaussians`: integer from 32,768 to 1,048,576. fal rounds it down to a multiple of 32.
- `num_inference_steps`: integer from 1 to 50. Fewer steps are faster and lose some detail.
- `guidance_scale`: number from 0 to 10.
- `seed`: integer from 0 to 2,147,483,647. Omit it or send `null` for a random seed.
- `enable_safety_checker`: must remain `true`.

This model has no time-shift (`rescale_t`) control. Use `idol-hf` if you need it, or more than 50 steps.

Example request:

```json
{
  "model": "idol-fal",
  "image_url": "https://example.com/object.png",
  "input": {
    "image_type": "real",
    "num_gaussians": 524288
  }
}
```

## Job lifecycle and output

1. Confirm `idol-fal` appears in `GET https://api.ai3d.dev/v2/models` and check `/v2/billing/prices`.
2. Submit to `POST /v2/jobs` with a fresh `Idempotency-Key` header (letters, digits, `.`, `_`, `:`, or `-`; maximum 128 characters). A successful submission returns `202 Accepted` and a job ID.
3. Poll `GET /v2/jobs/{job_id}` until the status is `succeeded`, `failed`, or `submission_unknown`.
4. On success, download the Gaussian PLY (role `splat`) and the background-removed `preprocessed_image` from the job's `artifacts` using their authenticated `download_url`. The PLY opens in the shared 3D viewer.

fal also returns a point-cloud preview GLB of the splat centres. AI3D does not archive it, so viewers open the splat itself. The predicted input camera, seed, and per-stage timings in fal's response are not archived either.

Retry timed-out submissions with the same body and idempotency key. Do not automatically create a second job when the status is `submission_unknown`; fal may have accepted the generation before its response was saved. Customer jobs require prepaid credits.

## Provider reference

- https://fal.ai/models/speridlabs/idol/llms.txt