# AI3D API v2 model: rodin-v25

Image-to-3D generation with Rodin v2.5.

- AI3D model ID: `rodin-v25`
- Task: `image_to_3d`
- AI3D provider adapter: `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: Requires a publicly reachable HTTPS source image in `image_url`.
- Request body: `input` is optional model-specific JSON; it may not exceed 16 KiB. The API supplies these defaults. Caller values in `input` override a default only where that field is an accepted input; fixed server settings cannot be overridden:

```json
{}
```

The API converts top-level `image_url` to a one-item provider `image_urls` array. Optional `input` fields include `prompt`, `tier`, `use_original_alpha`, `seed`, `geometry_file_format`, `material`, `quality_mesh_option`, `texture_mode`, `enable_creative_mode`, `hd_texture`, `texture_delight`, `is_micro`, `TAPose`, `bbox_condition`, `addons`, and `preview_render`.

Example request body:

```json
{
  "model": "rodin-v25",
  "image_url": "https://example.com/object.png",
  "input": {}
}
```

## Job lifecycle

1. Check `GET https://api.ai3d.dev/v2/models`; this model must appear in the enabled catalog. Also check `GET https://api.ai3d.dev/v2/billing/prices` for the current reservation estimate.
2. Submit the example 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}` with the same bearer key until `status` is `succeeded`, `failed`, or `submission_unknown`.
4. On success, read `artifacts` from the job response and download the required artifact using its authenticated `download_url`. A public `viewer_url` may be present for shareable 3D outputs.

When retrying a timed-out submission, resend the identical body with the same idempotency key. Never create a second job automatically when status is `submission_unknown`; provider acceptance and billing may need operator reconciliation. Customer jobs require prepaid credits, and final provider usage can differ from the estimate.

## Input and output notes

- Media URLs must use public HTTPS. For images, you can upload PNG, JPEG, or WebP up to 10 MiB with `POST /v2/uploads` and pass the returned signed `image_url`.
- This job uses the normal v2 asynchronous job and billing flow. Do not use an SDK or provider endpoint in place of the AI3D job API.
- Output artifact names and formats depend on the provider response. Inspect `artifacts`; do not assume a fixed filename or extension.

## Provider reference

- https://fal.ai/models/fal-ai/hyper3d/rodin/v2.5/llms.txt