# AI3D API v2 model: worldlabs

Generate a 3D world with World Labs Marble 1.1.

- AI3D model ID: `worldlabs`
- Task: `world_generation`
- AI3D provider adapter: `worldlabs`
- Availability: This model appears in `GET /v2/models` only when the World Labs 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: Provide `image_url`, `input.text_prompt`, or `input.world_prompt`. To combine text with an image, use `image_url` and `input.text_prompt`. Do not send both `image_url` and `input.world_prompt`.
- 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
{
  "permission": {
    "public": false
  }
}
```

`input.world_prompt` supports World Labs prompt types `text`, `image`, `multi-image`, and `video`. All URI sources must be public HTTPS. The API archives trusted returned files, including every SPZ resolution, and labels recognized World Labs outputs in each artifact record: `role` is `splat`, `collider`, `pano`, or `thumbnail`; SPZ records also include their provider `variant` when available. Every artifact record includes its provider `source_path`, file name, content type, size, and authenticated download URL. During finalization, already archived files are immediately listed and downloadable; failed jobs retain those files. Check `artifact_inventory` and `artifact_warnings` on the job for archived and omitted output counts.

Example request body:

```json
{
  "model": "worldlabs",
  "image_url": "https://example.com/object.png",
  "input": {
    "text_prompt": "A bright modern art museum with a central atrium"
  }
}
```

## 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`. You can also inspect `artifacts` while `status` is `finalizing`.
4. Read every listed artifact and use its `role`, optional `variant`, `source_path`, and `name` to identify it; download it with its authenticated `download_url`. Files listed during finalization are already archived. If the job fails, inspect its retained `artifacts`, `artifact_inventory`, and `artifact_warnings` before concluding which outputs are unavailable. 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://docs.worldlabs.ai/api/models