# AI3D API v2 model: image2worldviews

Generate a small set of directional images from one anchor image, sampled from one shared navigable world.

- AI3D model ID: `image2worldviews`
- Task: `image_to_world_views`
- AI3D provider adapter: `ai3d`
- Availability: Optional; use only when this model appears in `GET /v2/models`.
- Shared implementation guide: <https://api.ai3d.dev/v2/llms.txt>
- AI3D API reference: <https://api.ai3d.dev/v2/openapi.json>

## Request

Use the authenticated AI3D API. Do not call provider services directly or include provider credentials in a client.

- Method and URL: `POST https://api.ai3d.dev/v2/image2worldviews`
- Authentication: `Authorization: Bearer <AI3D_API_KEY>` with write permission and this model allowed on the key.
- Content type: `application/json`
- `image_url`: public HTTPS URL to one source image. Use `POST /v2/uploads` for a local PNG, JPEG, or WebP image up to 10 MiB.
- `views`: optional list of one to six unique directions: `left`, `right`, `up`, `down`, `forward`, `back`. The default is `left`, `right`, `up`, `back`.
- Source images must be PNG, JPEG, or WebP and no larger than 10 MiB.

Example:

```json
{
  "image_url": "https://example.com/room.png",
  "views": ["left", "right", "up", "back"]
}
```

## Job lifecycle and response

1. Confirm that `image2worldviews` appears in `GET /v2/models` and inspect its estimate in `GET /v2/billing/prices`.
2. Submit the request to `POST /v2/image2worldviews` with a fresh `Idempotency-Key` header. A successful submission returns `202 Accepted` and a v2 job UUID.
3. Poll `GET /v2/jobs/{job_id}` until `status` is `succeeded`, `failed`, or `submission_unknown`.
4. On success, read `source_image_url` for the anchor and `world_views` for each requested image. These URLs require the same bearer key. Generated images are PNG artifacts. For a public Viewern gallery, use `viewern_url` (or `viewer_url`) from the job response.
5. Use `GET /v2/image2worldviews/{job_id}/debug` to inspect requested directions, commands, capture times, image dimensions, and session timings.

The anchor is the source image and is not regenerated. Requested views are sampled from one world to preserve scene continuity; directions are semantic requests, not exact positions or angles. Left/right and forward/back use LingBot World 2 movement controls; up/down use relative camera-pose translation. These model-conditioned controls do not guarantee exact geometry or metric displacement. Read the debug output to see the actual commands and chunk used for each view.

Retry a timed-out request with the same idempotency key. Do not automatically resubmit a `submission_unknown` job because the provider may have accepted the session already. Customer jobs use the normal prepaid-credit reservation and settlement flow.

## Provider-independent behavior

This model guide describes the AI3D API contract. Provider selection, credentials, sessions, frame extraction, storage, and billing remain server-side implementation details.