# AI3D API v2 agent guide Use this file as the common integration instructions for AI agents implementing an AI3D generation or image-editing client. For iOS-specific implementation, follow the **Direct iOS clients** section below; do not apply the customer-key flow to a shipped iOS app. - Canonical API base: `https://api.ai3d.dev/v2` - OpenAPI schema: - API reference: - Current model catalog: - Current model prices and reservation estimates: - Public model-guide directory: - Model guides: `https://api.ai3d.dev/v2/models/{model_id}/llm.txt` - Tripo rigging and animation operations guide: ## Select a model Call `GET /v2/models` at runtime and use a model only if its ID appears in the response. The source files include guides for all v2 model IDs, including optional World Labs and native Tripo models that may be hidden until their provider credentials are configured. Customer key model allowlists and plan policy may further restrict use. Use each model's guide for required inputs and provider-specific settings. For Hugging Face Space models, submit jobs through AI3D rather than calling Gradio directly. The worker attempts Space wake-up when its owner-scoped `HF_TOKEN` is configured and authorized for that Space; client agents do not need or receive that credential. Read the model guide for cold-start behavior and output limitations. Tripo rig-check, auto-rigging, and animation retargeting are available as operations. `POST /v2/auto-rig` detects the rig type and creates one wallet-billed job; set `include_default_animations: true` to apply that type's documented defaults. Biped defaults are the five-clip FPS pack; quadruped, hexapod, and octopod have `walk`, while serpentine and aquatic have `march`. Tripo documents no default preset for avian rigs. The biped-only `include_fps_animations: true` option remains supported as an alias. `POST /v2/rig-check` accepts exactly one of your completed Tripo `source_job_id` or a public HTTPS GLB `model_url`, and returns a riggability verdict without a Tripo task ID. Both the `tripo-rig` and `tripo-auto-rig` catalog entries include this free utility when enabled. The direct Tripo gateway route `/v2/tripo/animations/rig-check` remains operator-only. Manual texture, convert, retopology, rig, retarget, auto-rig, and mesh segmentation jobs use the customer wallet and are listed in `GET /v2/models` once enabled. The mesh models are `tripo-segment` (existing model input), `tripo-smartsegment-image` (image pipeline), and `tripo-smartsegment-model` (public GLB pipeline); see their individual guides for request bodies, source rules, and settings. - `trellis-2` (image_to_3d; fal): - `trellis` (image_to_3d; fal): - `rodin-v2` (image_to_3d; fal): - `rodin-v25` (image_to_3d; fal): - `rodin` (image_to_3d; fal): - `hunyuan3d-v3` (image_to_3d; fal): - `hunyuan3d-v3-sketch` (image_to_3d; fal; retired 2026-11-01, not enabled): - `hunyuan3d-v21` (image_to_3d; fal): - `hunyuan3d-v2` (image_to_3d; fal): - `hunyuan3d-mini` (image_to_3d; fal): - `sam3d` (image_to_3d; fal): - `sam2-image` (image_to_image; fal): - `sam2-auto-segment` (image_to_image; fal): - `sam3-image` (image_to_image; fal): - `tripo-v25` (image_to_3d; fal): - `tripo-v31` (image_to_3d; fal): - `tripo-p1` (image_to_3d; fal): - `tripo-h31-image` (image_to_3d; tripo): - `tripo-h31-text` (text_to_3d; tripo): - `tripo-p1-image` (image_to_3d; tripo): - `tripo-p1-text` (text_to_3d; tripo): - `tripo-p1-multiview` (multiview_to_3d; tripo): - `tripo-image-to-multiview` (image_to_multiview; tripo): - `tripo-image-to-splat` (image_to_3d; tripo): - `tripo-edit-multiview` (edit_multiview; tripo): - `tripo-texture` (model_to_model; tripo): - `tripo-convert` (model_to_model; tripo): - `tripo-retopology` (model_to_model; tripo): - `tripo-rig` (model_to_model; tripo): - `tripo-auto-rig` (model_to_model; tripo): - `tripo-retarget` (model_to_model; tripo): - `tripo-segment` (model_to_model; tripo): - `tripo-smartsegment-image` (image_to_3d; tripo): - `tripo-smartsegment-model` (model_to_model; tripo): - `triposplat` (image_to_3d; fal): - `instantmesh` (image_to_3d; replicate): - `moge2` (image_to_3d; gradio): - `moge3` (image_to_3d; gradio): - `anigen` (image_to_3d; gradio): - `anigen-weight-transfer` (model_to_model; ai3d): - `anigen-mixamo-retarget` (model_to_model; ai3d): - `mixamo-rig-retarget` (model_to_model; ai3d): - `apple-sharp` (image_to_3d; gradio): - `idol` (image_to_3d; gradio): - `idol-hf` (image_to_3d; gradio): - `idol-fal` (image_to_3d; fal): - `hy-motion-mixamo` (text_to_motion; gradio): - `h3-max-3d-to-video` (video_to_video; fal): - `h3-max-image-to-video` (image_to_video; fal): - `flux-2-klein-realtime` (image_to_image; fal): - `flux-3-klein`: FLUX.3 Klein text-to-image; prompt-only, one image per job. Guide: - `sana-sprint` (text_to_image; fal): - `worldlabs` (world_generation; worldlabs): - `worldlabs-draft` (world_generation; worldlabs): - `image2worldviews` (image_to_world_views; ai3d): ## Authenticate and submit from a trusted client Read-only credentials can read jobs and call `POST /v2/jobs/recover`, but cannot upload or manage keys. Creating another customer key cannot expand the creator's permissions, model list, or quota ceilings. V2 job routes accept only v2 records; use v1 routes for v1 jobs. For a server, command-line tool, Unity tool, or other trusted client, use a customer AI3D API key in the `Authorization: Bearer ` header. The key needs write permission and must allow the requested model. Keep it in a server-side secret store; never embed it in a public client or send it to a provider. Submit JSON to `POST /v2/jobs`. Include the model ID, the source field named by its model guide (`image_url`, `video_url`, or model-specific prompt input), and optional model-specific settings in `input`. For a mesh output, optionally add top-level `viewer_style: "illustration"` to save the preferred viewer presentation with the job; compatible viewers apply it automatically. The default is `default`, and this field never changes provider generation inputs. `input` is limited to 16 KiB. Media URLs must use public HTTPS. Tripo model-processing jobs use endpoint-specific top-level sources: `tripo-segment` takes a completed native Tripo `source_job_id` or public `model_url`; Smart Segmentation's image pipeline takes `image_url`; its model pipeline takes a public GLB `model_url` and requires `input.transform`. Existing Tripo operations take `source_job_id` or `model_url`, except retarget, which requires `source_job_id`. See each guide. For images, `POST /v2/uploads` accepts PNG, JPEG, and WebP up to 10 MiB and returns a signed `image_url`. For AniGen, prefer `POST /v2/anigen` when the live server has Gemini enabled. It accepts an image and standard job options, chooses AniGen parameters from the image on the worker, and returns the normal job response with `parameter_selection` metadata. Read for its exact body, selection policy, and fallback to manual settings; the endpoint returns `503` while Gemini is disabled. For `hy-motion-mixamo`, read and accept the Tencent HY-Motion license and Acceptable Use Policy before submitting. The license excludes the European Union, United Kingdom, and South Korea, and prohibits using the model or its outputs to improve another AI model. Set `input.accepted` to `true` only after agreeing and confirming the request is in the licensed territory. The model accepts a text prompt and returns an animation-only GLB or BVH file; see and its license copy. AniGen's generated rig can be reused with `anigen-weight-transfer`: provide an owned completed mesh job as `source_job_id` or public GLB `model_url`, plus the owned AniGen job UUID in `input.anigen_job_id`. Use `anigen-mixamo-retarget` for an AniGen rig and `mixamo-rig-retarget` for a Mixamo-rigged Tripo GLB or public GLB URL. Both use the private first-party Mixamo clip library listed by authenticated `GET /v2/anigen/animations`, run locally in the AI3D Blender worker, preserve the mesh, and use the normal wallet-backed job lifecycle. Their individual guides list source requirements, limits, and prices. Use `Idempotency-Key` (1–128 characters from letters, digits, `.`, `_`, `:`, and `-`) for safe retries. A successful job submission returns `202 Accepted`. Poll `GET /v2/jobs/{job_id}` until the status is `succeeded`, `failed`, or `submission_unknown`. Also inspect `artifacts` while the job is `finalizing`: every listed file has already been archived and can be downloaded with its authenticated `download_url`. Failed jobs can retain files archived before a later output failed, so inspect their `artifacts` too; a failed job does not mean every generated file is unavailable. Each artifact has a `name`, byte `size`, `content_type`, and authenticated `download_url`. When known, it also has a `role` (for example `animation`, `splat`, `collider`, `pano`, `thumbnail`, `mask`, or `view`), a `variant` (such as a splat resolution or view direction), and `source_path` (the provider response field or list position where AI3D found it; this is not a URL). Roles are inferred from provider metadata and field names, so use `source_path` and `name` when a role is generic or uncertain. Do not hardcode artifact names or rely on list order; select by role/variant and use each returned `download_url`. The job's `artifact_inventory` reports discovered provider outputs, archived files, and omitted files; `artifact_warnings` identifies outputs that could not be archived. More than 128 output candidates are capped at 128 archived candidates and the job fails with `provider_artifact_limit_exceeded`; inspect the inventory and warnings for omissions. When a request times out, retry the same request with the same idempotency key. Do not automatically resubmit an unknown job or a `submission_unknown` job: the provider may have accepted it and the charge may require reconciliation. Customer jobs reserve prepaid credits before dispatch. Use `/v2/billing/prices` for current estimates; final usage can change the amount charged. The API owns provider credentials, job dispatch, polling, artifact archival, and usage settlement. Implement against AI3D's v2 API, not provider URLs. Read the version-specific [API guide](https://api.ai3d.dev/v2/docs) and each model guide for precise input requirements. ## Direct iOS clients A shipped iOS app that calls AI3D directly must use the registered app's App Attest flow and a short-lived mobile access token. Never place a customer API key, operator key, or provider credential in the app. The app publisher must provide the app ID, bundle ID, and App ID prefix; do not guess these values or copy them from another app. 1. Create or retrieve a per-installation key with Apple's `DCAppAttestService`; store its key ID in Keychain. 2. Request a one-time challenge from `POST /v2/mobile/apps/{app_id}/challenges` with `{"purpose":"attest"}`. Base64-decode `challenge`, hash the decoded bytes with SHA-256, pass that hash to `attestKey`, then send the base64 attestation object to `POST /v2/mobile/apps/{app_id}/attest`. 3. To obtain a bearer token, request a fresh challenge with `{"purpose":"token","key_id":"..."}`, hash its decoded challenge bytes with SHA-256, call `generateAssertion`, and send its base64 result to `POST /v2/mobile/apps/{app_id}/tokens`. 4. Keep the returned token in memory. It expires after 900 seconds. Serialize token exchanges per installation so assertion counters arrive in order; obtain a fresh challenge and assertion when renewing it. 5. Use the mobile token only for `POST /v2/uploads`, `POST /v2/jobs`, reads of jobs created by that installation, and downloads of their artifacts. Mobile jobs are private by default. Publishing a job requires an explicit `POST /v2/jobs/{job_id}/share` request. The token response's `allowed_models` is the app's model allowlist. Intersect it with the public `GET /v2/models` catalog and the product scope requested by the app owner, then read each chosen model guide. Do not assume that every enabled API model belongs in the iOS app. Mobile tokens cannot access account or billing operations, manage app registrations, call the Tripo passthrough gateway, or use compatibility routes. For simulator work, mock API behavior for UI tests. A local Debug integration may use a dedicated customer key injected at runtime, but never an operator key and never a key embedded in source or a Release build. Real App Attest verification requires a supported physical device; real generation jobs can incur charges. See the API's [backend-free iOS guide](https://api.ai3d.dev/v2/docs) for registration details, response examples, sharing, and simulator guidance. ## Blender scene scripts (operator only) The separately gated `blender` script runner uses `POST /v2/blender` or the normal job endpoint, runs scene-building Python on a dedicated CPU execution, and returns GLB, optional PNG views, statistics and logs. It accepts trusted operator keys only, has no GPU requirement, and is disabled until its separate runner is deployed. Read before integration. ## World Labs Atlas / Marble 2 beta (operator only) Chisel world-building demo: . Explore actual SPZ scenes fitted from Chisel RGBD, compare base and extended coverage, and inspect the exact inputs. Supporting experiments retain the layout, posed-reference, mask and point-cloud evidence. Published examples need no key; new beta jobs require an eligible operator key. Separate photo-to-view example using images-to-RGBD and generate: . This is not a Chisel example. - `worldlabs2-text-to-image` (text_to_image; worldlabs2): - `worldlabs2-images-to-rgbd` (image_to_rgbd; worldlabs2): - `worldlabs2-generate` (posed_image_to_image; worldlabs2): - `worldlabs2-chisel` (depth_to_image; worldlabs2): - `worldlabs2-inpaint` (posed_image_inpaint; worldlabs2): - `worldlabs2-images-to-splat` (posed_rgbd_to_splat; worldlabs2): - `worldlabs2-splat-to-mesh` (splat_to_mesh; worldlabs2):