# 3D Object Generation (/docs/3d)


Endpoint [#endpoint]

```
POST /v1/3d/generations
```

Request [#request]

```json
{
  "model": "model-id",
  "prompt": "A low-poly medieval castle with towers and a moat",
  "format": "glb"
}
```

Parameters [#parameters]

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `model`   | string | Yes      | 3D model ID                         |
| `prompt`  | string | Yes      | Text description of the 3D object   |
| `format`  | string | No       | Output format (`glb`, `obj`, `fbx`) |

Response [#response]

3D generation is asynchronous:

```json
{
  "id": "3d_abc123",
  "status": "processing",
  "created_at": 1709251200
}
```

Check Status [#check-status]

```
GET /v1/3d/generations/{id}
```

When complete:

```json
{
  "id": "3d_abc123",
  "status": "completed",
  "model_url": "https://api.yuhuanstudio.com/v1/temp-images/3d_abc123.glb"
}
```

Available Models [#available-models]

<Callout type="info">
  For a list of available 3D models and their capabilities, please use the [Models API](/docs/models-api) with `GET /v1/models?type=3d_generation`.
</Callout>

Example [#example]

```python
import httpx
import time

response = httpx.post(
    "https://api.yuhuanstudio.com/v1/3d/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "model-id",
        "prompt": "A futuristic sports car, metallic blue finish",
        "format": "glb"
    }
)

task = response.json()
task_id = task["id"]

# Poll for completion
while True:
    status = httpx.get(
        f"https://api.yuhuanstudio.com/v1/3d/generations/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    ).json()

    if status["status"] == "completed":
        print(f"3D model ready: {status['model_url']}")
        break
    elif status["status"] == "failed":
        print(f"Generation failed: {status.get('error')}")
        break

    time.sleep(5)
```

<Callout type="info">
  3D generation is an emerging capability. Available models depend on your provider configuration. Check `GET /v1/models?type=3d_generation`.
</Callout>