# PATINA · Material API

> Trình tạo kết cấu từ văn bản, xuất hình ảnh có thể lát cùng bản đồ PBR, hỗ trợ img2img và inpainting tùy chọn

Tạo họa tiết có thể lát từ lời nhắc và dự đoán các bản đồ PBR: basecolor, normal, roughness, metalness và height. Dùng `tiling_mode` để lát cả hai hướng, ngang hoặc dọc, và `upscale_factor` có giá trị 0, 2 hoặc 4 để phóng lớn các bản đồ. Truyền `image_url` để bật image-to-image, thêm `mask_url` để bật inpainting. Tối đa 4 hình ảnh mỗi yêu cầu.

- Model id: `patina/material`
- Made by: Open model
- Category: Text to Image
- Output: image
- Price per run: from $0.08 / run (cheapest run $0.08 (80 API credits))
- Run: `POST https://api.doitong.com/v1/run/patina/material`
- Quote: `POST https://api.doitong.com/v1/quote/patina/material`
- Docs page: https://doitong.com/vi/developers/models/patina/material

## Pricing

Price: **from $0.08 / run** (the lowest tier; the quote prices your exact input). Price per run: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $0.08 = 80 API credits (1 run × $0.08).

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/patina/material` 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 |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  |  | Mô tả bằng văn bản về vật liệu hoặc kết cấu cần tạo. |
| `image_size` |  | object {width, height} \| enum (string) | no | `square_hd` | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9` | Kích thước pixel của kết cấu kết quả. |
| `num_inference_steps` |  | integer | no | `8` | 1 – 8 | Số bước khử nhiễu dùng để tạo kết cấu. |
| `seed` |  | integer \| null | no |  |  | Seed ngẫu nhiên giúp tái tạo kết quả tạo sinh. |
| `num_images` | `num_outputs` | integer | no | `1` | 1 – 4 | Số lượng hình ảnh kết cấu cần tạo. |
| `enable_prompt_expansion` |  | boolean | no | `true` |  | Bật mở rộng lời nhắc dựa trên LLM để bổ sung chi tiết. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Bật kiểm tra an toàn cho hình ảnh được tạo. |
| `tiling_mode` |  | enum (string) | no | `both` | `both`, `horizontal`, `vertical` | Hướng lát: 'both' để lát đa hướng, 'horizontal' hoặc 'vertical'. |
| `tile_size` |  | integer | no | `128` | 32 – 256 | Kích thước ô trong không gian tiềm ẩn, trong đó 64 tương ứng với 512px và 128 tương ứng với 1024px. Trên mỗi trục được lát, kích thước hình ảnh được tạo sẽ đặt giới hạn trên tự động. |
| `tile_stride` |  | integer | no | `64` | 16 – 128 | Đặt bước dịch giữa các ô trong không gian tiềm ẩn; giới hạn tự động ngăn giá trị vượt quá một nửa kích thước ô hiệu dụng. |
| `image_url` | `image` | string (image URL) \| null | no |  |  | URL hình ảnh nguồn, được dùng để inpainting nếu đi kèm mask_url và dùng cho xử lý image-to-image trong các trường hợp khác. |
| `mask_url` | `mask` | string (image URL) \| null | no |  |  | URL mặt nạ inpainting được cung cấp cùng image_url bắt buộc. Mặt nạ giữ nguyên các vùng đen và tạo lại các vùng trắng. |
| `strength` |  | number | no | `0.6` | ≤ 1, > 0 | Cường độ biến đổi chỉ áp dụng cho hình ảnh được cung cấp qua image_url; nếu không thì không được sử dụng. |
| `maps` |  | array of enum (string) | no | `["basecolor","normal","roughness","metalness","height"]` |  | Các bản đồ PBR được chọn để dự đoán, theo mặc định cả năm bản đồ đều được chọn. Không chọn bản đồ nào sẽ bỏ qua hoàn toàn việc ước tính PBR. |
| `upscale_factor` |  | enum (integer) | no | `0` | `0`, `2`, `4` | Hệ số nâng cấp liền mạch SeedVR áp dụng cho các bản đồ PBR được dự đoán nhưng giữ kết cấu cơ sở ở độ phân giải ban đầu. Chọn 2 để tăng gấp đôi độ phân giải, 4 để tăng gấp bốn lần hoặc 0 để tắt nâng cấp. |
| `output_format` |  | enum (string) | no | `png` | `jpeg`, `png`, `webp` | Định dạng tệp hình ảnh cho kết cấu đầu ra và bản đồ PBR. |

File parameters (`image`, `mask`) 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
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

## 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/patina/material?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }'

# 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/patina/material?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }),
});
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 = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/patina/material", 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": "patina/material",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
      },
      "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": "patina/material",
  "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": 80,
    "usd": "0.08",
    "charged": 80,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  },
  "output": {
    "images": [
      {
        "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
      }
    ],
    "seed": 42,
    "prompt": "string",
    "timings": {}
  },
  "outputs": [
    {
      "type": "image",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "width": 1024,
      "height": 768,
      "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 |
|---|---|---|
| `images` | array of any | Hình ảnh đầu ra bao gồm các bản đồ vật liệu PBR do PATINA dự đoán cùng với các kết cấu có thể lát được tạo bởi z-image. |
| `seed` | integer | Seed được áp dụng khi tạo kết cấu. |
| `prompt` | string | Lời nhắc tạo kết cấu, bao gồm mọi phần mở rộng đã áp dụng. |
| `timings` | object | Phân tích thời gian bao quát toàn bộ quá trình, tính theo giây. |

## Related models

- [PATINA](https://doitong.com/developers/models/patina.md) (`patina`): from $0.0225 / run of input image
- [PATINA · Material · Extract](https://doitong.com/developers/models/patina/material/extract.md) (`patina/material/extract`): from $0.17 / run
- [FLUX.1 \[dev\]](https://doitong.com/developers/models/flux/dev.md) (`flux/dev`): $0.025 / megapixel
- [FLUX.1 \[schnell\]](https://doitong.com/developers/models/flux/schnell.md) (`flux/schnell`): $0.003 / megapixel
- [FLUX.2 \[dev\]](https://doitong.com/developers/models/flux-2.md) (`flux-2`): $0.012 / megapixel
- [FLUX.2 \[pro\]](https://doitong.com/developers/models/flux-2-pro.md) (`flux-2-pro`): $0.015 / megapixel of output image
- [GPT Image 2.5 Text to Image](https://doitong.com/developers/models/openai/gpt-image-2.5/flare/text-to-image.md) (`openai/gpt-image-2.5/flare/text-to-image`): from $0.008 / image
- [Ideogram V4.5](https://doitong.com/developers/models/ideogram/v4.5.md) (`ideogram/v4.5`): from $0.03 / image

## Links

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