# AI3D API v2 model: idol-hf

Generate a Gaussian-splat object from one image through the Yosun idol-try Hugging Face Space.

- AI3D model ID: `idol-hf`
- Task: `image_to_3d`
- AI3D provider adapter: `gradio` (Hugging Face Space)
- Space: <https://huggingface.co/spaces/Yosun/idol-try>
- Related models: `idol` is the general route. It sends a job here by default, or to `idol-fal` (the same model on fal.ai) while this Space has a job in flight. Submit to `idol-hf` directly to always use the Space.
- Availability: Check `GET https://api.ai3d.dev/v2/models`; customer-key model allowlists and deployment availability may restrict use.
- 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 Space directly or put Hugging Face credentials in a 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 in `image_url`.
- Price: fixed AI3D price of $0.10 per Hugging Face Space job. Check `/v2/billing/prices` before submission.
- Request settings: `input` may be omitted or contain only the fields below; the API supplies these defaults:

```json
{
  "mode": "Synthetic",
  "steps": 50,
  "cfg_scale": 3.0,
  "rescale_t": 3.0,
  "seed": 42,
  "randomize": false,
  "gaussians": "262,144"
}
```

Accepted settings:

- `mode`: `Synthetic` or `Real photo`.
- `steps`: integer from 10 to 100; default `50`.
- `cfg_scale`: number from 0 to 10; default `3.0`.
- `rescale_t`: number from 1 to 6; default `3.0`.
- `seed`: integer from 0 to 2,147,483,647; default `42`.
- `randomize`: boolean; default `false`. When true, the Space replaces the supplied seed with a random seed.
- `gaussians`: one of `65,536`, `131,072`, `262,144`, `524,288`, or `1,048,576`; default `262,144`.

Example request:

```json
{
  "model": "idol-hf",
  "image_url": "https://example.com/object.png",
  "input": {
    "mode": "Real photo",
    "gaussians": "524,288"
  }
}
```

## Job lifecycle and output

1. Confirm `idol-hf` 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`. 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 artifact from its authenticated `download_url`. The PLY opens in the shared 3D viewer when it is recognized as a Gaussian splat.

The Space also returns a seed and a settings summary, but AI3D archives downloadable provider files as job artifacts. The Space's own `HF_TOKEN` secret must have access to `facebook/dinov3-vith16plus-pretrain-lvd1689m` and `black-forest-labs/FLUX.2-dev`; API clients do not need either Hugging Face access or credentials. The Space can be paused or cold-starting, which delays jobs while the worker wakes it.

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