# AI3D API v2 model: hunyuan3d-v3-sketch

**Retired on 2026-11-01. Do not use.** fal no longer serves `fal-ai/hunyuan3d-v3/sketch-to-3d`, so this model was removed from `GET /v2/models` and `GET /v2/billing/prices`, and `POST /v2/jobs` rejects it with HTTP 400. The rest of this guide is kept only as a record of the former interface. For image input use `hunyuan3d-v3` (see `/v2/models`).

Sketch-to-3D generation with Hunyuan3D v3.

- AI3D model ID: `hunyuan3d-v3-sketch`
- 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
{}
```

Use a sketch image as `image_url`; model options are passed in `input`.

Example request body:

```json
{
  "model": "hunyuan3d-v3-sketch",
  "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/hunyuan3d-v3/sketch-to-3d/llms.txt