# AI3D API v2 model: tripo-h31-image

Image-to-3D generation with native Tripo v3.1 API.

- AI3D model ID: `tripo-h31-image`
- Task: `image_to_3d`
- AI3D provider adapter: `tripo`
- Availability: This model appears in `GET /v2/models` only when the v2 Tripo credential is configured.
- 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
{
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true
}
```

The source is `image_url`. Supported settings include `texture`, `pbr`, `texture_quality` (`fast`, `standard`, `detailed`, or `extreme`), `geometry_quality` (`standard` or `detailed`), `quad`, `smart_low_poly`, `generate_parts`, `face_limit`, `model_seed`, and texture options. The Tripo version is pinned server-side to `v3.1-20260211`; do not send `input.model`. Only settings supported by Tripo v3 are accepted.

Example request body:

```json
{
  "model": "tripo-h31-image",
  "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://developers.tripo3d.com/en/docs/generation-image-to-model/standard