# VGGT-1B API

> يعيد بناء مشهد ثلاثي الأبعاد من 48 صورة أو فيديو كحد أقصى، مع إعادة خرائط العمق ووضعيات الكاميرا وسحابة نقطية

يقدّر الهندسة من مشاهد متعددة. قدّم ما يصل إلى 48 صورة في `image_urls`، وأضف اختياريًا `video_url` مع أخذ عينات كل `frame_sampling_rate` إطارًا. يعيد خرائط عمق لكل إطار، والمعلمات الخارجية والداخلية للكاميرا، وملفات التنبؤ الخام، وسحابة نقطية GLB مع مخاريط الكاميرا. يتحكم `confidence_percentile` و`max_points` في كثافة السحابة النقطية.

- Model id: `vggt-1b`
- Made by: Meta
- Category: Vision
- Output: json
- Charged by usage (up to $1.755 per run, typical $0.04; the rest of the hold is refunded): $0.000975 / second of processing time (cheapest run $0.04 (40 API credits))
- Run: `POST https://api.doitong.com/v1/run/vggt-1b`
- Quote: `POST https://api.doitong.com/v1/quote/vggt-1b`
- Docs page: https://doitong.com/ar/developers/models/vggt-1b

## Pricing

Price: **$0.000975 / second of processing time**. Charged by actual usage at $0.000975 / second of processing time: up to $1.755 per run (the quote gives the maximum for your input), the rest is refunded automatically after the run. A typical run costs $0.04.

The full example input below holds up to $1.755 = 1755 API credits (up to 1800 s of processing time × $0.000975) when it starts; a typical run costs $0.04 (40 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). This model is charged by usage: `POST https://api.doitong.com/v1/quote/vggt-1b` with the same JSON body returns the most the run can cost for that input (`credits`, debited when the run starts); after the run you pay the usage the model reports and the rest is refunded automatically. An input whose maximum would exceed the per-run limit is refused with 422. 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_urls` | `images` | array of image URL | no |  | ≤ 48 items | صور مصدر إعادة البناء، تُضاف حواشٍ إلى كل منها لتصبح مربعة ثم يُعاد تحجيمها بحيث يكون أطول بُعد 518 بكسل. تُقبل صيغ JPEG وPNG وWEBP وأي تنسيق صورة إضافي يستطيع Pillow فك ترميزه. |
| `video_url` | `video` | string (video URL) \| null | no |  |  | فيديو مصدر اختياري تتبع إطاراته المأخوذة image_urls في المدخل المدمج. تُؤخذ عينة من كل إطار `frame_sampling_rate`، مع تضمين الإطار الأول والأخير دائمًا. |
| `frame_sampling_rate` |  | integer | no | `24` | 1 – 1,000 | الفاصل بين الإطارات المطبّق فقط عند توفير فيديو عبر `video_url`؛ ولا تأثير له خلاف ذلك. يُحتفظ بإطاري الحدّين مهما كان الفاصل، مع أخذ كل إطار n بينهما. |
| `alpha_blend_onto` |  | enum (string) | no | `white` | `keep`, `white`, `black`, `mean` | توفّر معالجة قناة ألفا أربعة خيارات: يزيل 'keep' ألفا دون تغيير قيم البكسلات الأصلية؛ ويُركّب 'mean' الصورة فوق متوسط RGB الخاص بـ ImageNet. للخلفية المصمتة، اختر 'white' أو 'black' للتركيب فوق اللون المقابل. |
| `export_prediction_data` |  | boolean | no | `true` |  | تصدير التنبؤات الخام كملفات JSON منفصلة للإطارات الفردية. يتضمن كل ملف العمق ودرجة الثقة الخاصة به، وقناعًا، ووضعية الكاميرا المرمّزة. |
| `export_depth_maps` |  | boolean | no | `true` |  | تصدير بيانات العمق النقطية مع تحويل خطي من `depth_range` إلى قيم بكسلات بين 0 و65535. يحصل كل إطار على ملف PNG رمادي منفصل بدقة 16-bit. |
| `export_point_cloud` |  | boolean | no | `true` |  | تصدير سحابة النقاط الملوّنة والمدمجة بتنسيق GLB، مع تمثيل الكاميرات المقدّرة بشبكات مخروطية منفردة في المشهد. |
| `array_encoding` |  | enum (string) | no | `base64` | `base64`, `list` | تنسيق تخزين المصفوفة لملفات JSON الخاصة بالتنبؤ؛ إذ يستهلك 'list' مساحة أكبر بكثير من 'base64'. اختر 'list' للقوائم المتداخلة في JSON أو 'base64' للكائنات التي تحتوي على {data, shape, dtype}. |
| `exclude_keys` |  | array of enum (string) | no |  |  | المفاتيح المستبعدة من كل ملف JSON للتنبؤ. |
| `confidence_percentile` |  | number | no | `50` | 0 – 100 | نسبة التصفية المعتمدة على الثقة لإنشاء سحابة النقاط: تعطّل القيمة 0 التصفية، بينما تستبعد القيم الأخرى تلك النسبة من النقاط، بدءًا من الأقل ثقة. |
| `max_points` |  | integer | no | `250000` | 1,000 – 5,000,000 | الحد الأقصى لعدد نقاط GLB، وقيمته الافتراضية 250,000. لتقليل زمن التسلسل والرفع، تُكتب عينة موزعة بالتساوي عند تجاوز السحابة لهذه الميزانية. |
| `enable_safety_checker` |  | boolean | no | `true` |  | مفتاح فحص السلامة لصور المدخل والفيديو. |

File parameters (`images`, `video`) 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
{}
```

A fuller example:

```json
{}
```

## 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/vggt-1b?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 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/vggt-1b?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});
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 = {}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/vggt-1b", 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": "vggt-1b",
      "input": {},
      "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": "vggt-1b",
  "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": 1755,
    "usd": "1.755",
    "charged": 1755,
    "refunded": 0
  },
  "input": {},
  "output": {
    "point_cloud": {
      "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
    },
    "depth_maps": [
      {
        "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,
        "width": 1024,
        "height": 768
      }
    ],
    "prediction_data": [
      {
        "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
      }
    ],
    "num_frames": 1,
    "depth_range": [
      1.0
    ],
    "extrinsics": [
      [
        [
          1.0
        ]
      ]
    ],
    "intrinsics": [
      [
        [
          1.0
        ]
      ]
    ],
    "timings": {}
  },
  "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 |
|---|---|---|
| `point_cloud` | object {url, content_type, file_name, file_size} \| null | تصدير سحابة النقاط المُعاد عندما تكون `export_point_cloud` صحيحة؛ ويجمع مشهد GLB الخاص بها السحابة المدمجة مع مخاريط الكاميرات. |
| `depth_maps` | array of object {url, content_type, file_name, file_size, width, height} | تصدير خريطة العمق المتاح عندما تكون `export_depth_maps` صحيحة. تتبع العناصر تسلسل إطارات المصدر، ويمثل كل إطار بيانات PNG نقطية رمادية بعمق 16-bit. |
| `prediction_data` | array of object {url, content_type, file_name, file_size} | تصدير التنبؤ الخام: عندما تكون `export_prediction_data` صحيحة، يملك كل إطار ملف JSON خاصًا به، وتتبع الملفات تسلسل الإطارات. |
| `num_frames` | integer | إجمالي عدد الإطارات المُعاد بناؤها، بما في ذلك الصور والإطارات المأخوذة من الفيديو. |
| `depth_range` | array of number | حدود العمق [min, max] المستخدمة لتكميم `depth_maps`. استعد العمق بالصيغة min + pixel * (max - min) / 65535. |
| `extrinsics` | array of array of array of number | مصفوفات التحويل الخارجية من الكاميرا إلى العالم، بحجم 3x4 لكل إطار؛ وتشير محاور OpenCV إلى اليمين على x، وإلى الأسفل على y، وإلى الأمام على z. |
| `intrinsics` | array of array of array of number | مصفوفات التحويل الداخلية للكاميرا ذات الثقب الدبوسي، بحجم 3x3 لكل إطار، معبَّر عنها بإحداثيات البكسلات في إطار النموذج بحجم 518x518. |
| `timings` | object | الوقت المنقضي لكل مرحلة، بالثواني. |

## Related models

- [Sam 3 · Image · Embed](https://doitong.com/developers/models/sam-3/image/embed.md) (`sam-3/image/embed`): $0.005 / run
- [Bagel · Understand](https://doitong.com/developers/models/bagel/understand.md) (`bagel/understand`): $0.05 / request
- [Bria Ad Delayer](https://doitong.com/developers/models/bria/ad-delayer.md) (`bria/ad-delayer`): $0.30 / request
- [Florence 2 Large Caption](https://doitong.com/developers/models/florence-2-large/caption.md) (`florence-2-large/caption`): $0.003 / run
- [Florence 2 Large Detailed Caption](https://doitong.com/developers/models/florence-2-large/detailed-caption.md) (`florence-2-large/detailed-caption`): $0.004 / run
- [Florence 2 Large OCR](https://doitong.com/developers/models/florence-2-large/ocr.md) (`florence-2-large/ocr`): $0.003 / run
- [Florence 2 Large Region To Category](https://doitong.com/developers/models/florence-2-large/region-to-category.md) (`florence-2-large/region-to-category`): $0.003 / run
- [Florence-2 Large · More Detailed Caption](https://doitong.com/developers/models/florence-2-large/more-detailed-caption.md) (`florence-2-large/more-detailed-caption`): $0.004 / run

## Links

- HTML page: https://doitong.com/developers/models/vggt-1b
- 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=vggt-1b
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/vggt-1b