# Sam 3 · 3D Objects API

> Tái dựng đối tượng 3D từ ảnh, được chọn bằng lời nhắc văn bản, điểm, hộp hoặc mặt nạ, với đầu ra splat

Chuyển các đối tượng trong ảnh thành tài sản 3D. Chọn đối tượng bằng `mask_urls`, `prompt` văn bản, `point_prompts` hoặc `box_prompts`; nhiều hộp sẽ tạo các đối tượng riêng biệt. `detection_threshold` nhận giá trị từ 0.1 đến 1, còn `export_textured_glb` sẽ tích hợp kết cấu và UV. Đầu ra gồm GLB, các tệp Gaussian splat, tệp cho từng đối tượng trong cảnh nhiều đối tượng, siêu dữ liệu và gói zip.

- Model id: `sam-3/3d-objects`
- Made by: Meta
- Category: Image to 3D
- Output: 3d
- Estimated price per run: $0.02 / run (cheapest run $0.02 (20 API credits))
- Run: `POST https://api.doitong.com/v1/run/sam-3/3d-objects`
- Quote: `POST https://api.doitong.com/v1/quote/sam-3/3d-objects`
- Docs page: https://doitong.com/vi/developers/models/sam-3/3d-objects

## Pricing

Price: **$0.02 / run**. Estimated from the typical cost of one run. The quote is exactly what the run charges.

The full example input below costs $0.02 = 20 API credits (1 request × 20 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/sam-3/3d-objects` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `image_url` | `image` | string (image URL) | yes |  |  | URL hình ảnh để tái tạo 3D. |
| `mask_urls` |  | array of image URL | no |  |  | Danh sách URL mặt nạ tùy chọn cho từng đối tượng. Khi không có mặt nạ, phân đoạn tự động sử dụng lời nhắc, point_prompts hoặc box_prompts nếu được cung cấp; nếu không cung cấp mặt nạ hoặc lời nhắc phân đoạn, toàn bộ hình ảnh sẽ được sử dụng. |
| `prompt` |  | string \| null | no | `car` |  | Văn bản dùng cho phân đoạn tự động khi không có mặt nạ, chẳng hạn như 'chair' hoặc 'lamp'. |
| `point_prompts` |  | array of object {x, y, label, object_id} | no | `[]` |  | Các lời nhắc dựa trên điểm dùng cho phân đoạn tự động khi không có mặt nạ. |
| `point_prompts[].x` |  | integer \| null | no |  |  | Vị trí lời nhắc trên trục X. |
| `point_prompts[].y` |  | integer \| null | no |  |  | Vị trí lời nhắc trên trục Y. |
| `point_prompts[].label` |  | enum (integer) \| null | no |  | `0`, `1` | Nhãn tiền cảnh/hậu cảnh: 1 biểu thị tiền cảnh; 0 biểu thị hậu cảnh. |
| `point_prompts[].object_id` |  | integer \| null | no |  |  | Mã định danh tùy chọn để nhóm các lời nhắc tinh chỉnh một vật thể duy nhất. Nếu cũng cung cấp văn bản làm lời nhắc, mã định danh này xác định vật thể được phát hiện mà các điểm đó sẽ tinh chỉnh. |
| `box_prompts` |  | array of object {x_min, y_min, x_max, y_max, object_id} | no | `[]` |  | Các lời nhắc hộp tạo ra mặt nạ riêng cho từng đối tượng để tái tạo 3D thông qua phân đoạn tự động, chỉ được sử dụng khi không cung cấp mặt nạ. Có thể gửi nhiều hộp. |
| `box_prompts[].x_min` |  | integer \| null | no |  |  | Tọa độ x tối thiểu của hộp. |
| `box_prompts[].y_min` |  | integer \| null | no |  |  | Tọa độ y tối thiểu của hộp. |
| `box_prompts[].x_max` |  | integer \| null | no |  |  | Tọa độ X lớn nhất của hộp. |
| `box_prompts[].y_max` |  | integer \| null | no |  |  | Tọa độ Y lớn nhất của hộp. |
| `box_prompts[].object_id` |  | integer \| null | no |  |  | Mã định danh tùy chọn để nhóm các hộp tinh chỉnh một vật thể duy nhất. |
| `seed` |  | integer \| null | no |  |  | Seed dùng để tạo ngẫu nhiên có thể tái tạo. |
| `pointmap_url` |  | string \| null | no |  |  | URL tùy chọn để cải thiện ước tính độ sâu trong tái tạo 3D bằng cách cung cấp dữ liệu pointmap hoặc độ sâu bên ngoài dưới dạng NPY hoặc NPZ. |
| `detection_threshold` |  | number \| null | no |  | 0.1 – 1 | Ngưỡng độ tin cậy phát hiện; nếu bỏ qua, sử dụng giá trị mặc định của mô hình. Giá trị nằm trong khoảng từ 0.1 đến 1.0, trong đó giá trị nhỏ hơn đánh đổi độ chính xác để tăng số lượng phát hiện. |
| `export_textured_glb` |  | boolean | no | `false` |  | Tùy chọn xuất GLB: bật tùy chọn này sẽ thay màu đỉnh bằng kết cấu đã dựng sẵn và UV. |

File parameters (`image`, `mask_urls`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "image": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

A fuller example:

```json
{
  "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.com/v1/run/sam-3/3d-objects?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/sam-3/3d-objects?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/sam-3/3d-objects", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.com/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "sam-3/3d-objects",
      "input": {
        "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "sam-3/3d-objects",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 20,
    "usd": "0.02",
    "charged": 20,
    "refunded": 0
  },
  "input": {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  },
  "output": {
    "gaussian_splat": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "model_glb": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "metadata": [
      {
        "object_index": 1,
        "scale": [
          []
        ],
        "rotation": [
          []
        ],
        "translation": [
          []
        ],
        "camera_pose": [
          []
        ]
      }
    ],
    "individual_splats": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      }
    ],
    "individual_glbs": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      }
    ],
    "artifacts_zip": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `gaussian_splat` | object {url, content_type, file_name, file_size} | Splat cảnh kết hợp cho kết quả có nhiều đối tượng hoặc một splat duy nhất trong trường hợp còn lại; được cung cấp dưới dạng tệp Gaussian splat ở định dạng .ply. |
| `model_glb` | object {url, content_type, file_name, file_size} | Đầu ra 3D được lưu dưới dạng GLB: nhiều đối tượng được ghép thành một cảnh, trong khi các kết quả khác chứa một lưới. |
| `metadata` | array of object {object_index, scale, rotation, translation, camera_pose} | Siêu dữ liệu cho từng đối tượng, bao gồm phép quay, phép tịnh tiến và tỷ lệ. |
| `individual_splats` | array of object {url, content_type, file_name, file_size} \| null | Các tệp Gaussian splat riêng cho từng đối tượng, chỉ khả dụng trong các cảnh có nhiều đối tượng. |
| `individual_glbs` | array of object {url, content_type, file_name, file_size} \| null | Các tệp lưới GLB riêng cho từng đối tượng, chỉ khả dụng trong các cảnh có nhiều đối tượng. |
| `artifacts_zip` | object {url, content_type, file_name, file_size} \| null | Tệp lưu trữ ZIP chứa tất cả thành phần và siêu dữ liệu. |

## Related models

- [Sam 3 · Image RLE](https://doitong.com/developers/models/sam-3/image-rle.md) (`sam-3/image-rle`): $0.005 / run
- [Segment Anything Model 3](https://doitong.com/developers/models/sam-3/image.md) (`sam-3/image`): $0.005 / run
- [Sam 3 · Video](https://doitong.com/developers/models/sam-3/video.md) (`sam-3/video`): $0.005 / 16 frames of input video
- [Sam 3 · Video RLE](https://doitong.com/developers/models/sam-3/video-rle.md) (`sam-3/video-rle`): $0.005 / 16 frames of input video
- [Sam 3 · 3D Body](https://doitong.com/developers/models/sam-3/3d-body.md) (`sam-3/3d-body`): $0.02 / run
- [Sam 3 · 3D Align](https://doitong.com/developers/models/sam-3/3d-align.md) (`sam-3/3d-align`): $0.02 / run
- [Sam 3 · Image · Embed](https://doitong.com/developers/models/sam-3/image/embed.md) (`sam-3/image/embed`): $0.005 / run
- [Hi3D Image to 3D](https://doitong.com/developers/models/hitem3d/hi3d/image-to-3d.md) (`hitem3d/hi3d/image-to-3d`): $0.50 / run

## Links

- HTML page: https://doitong.com/developers/models/sam-3/3d-objects
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=sam-3/3d-objects
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/sam-3/3d-objects