# 모델링 등록하기

모델링은 파트너사의 3D 모델 파일을 Archisketch에 등록하는 첫 번째 단계입니다. 생성된 모델링 ID는 이후 [컴포넌트 생성](/dev/api-2/3d-product-integration/component.md)에 사용됩니다.

모든 API 요청 헤더에 `X-API-KEY`를 포함해야 합니다. 발급 방법은 [API 사용 방법](/dev/api.md)을 참고하세요.

```http
X-API-KEY: {x-api-key}
```

## 모델링 생성하기

**POST** `/api/v1/modelings`

요청은 `multipart/form-data` 형식으로 전송합니다.

{% stepper %}
{% step %}

### 파일 준비하기

업로드할 3D 모델 파일과 모델링 이름을 준비하세요.

| 필드            | 타입      |  필수 | 설명           |
| ------------- | ------- | :-: | ------------ |
| name          | string  |  ✅  | 모델링 이름       |
| file          | file    |  ✅  | 3D 모델 파일     |
| isPersonal    | boolean |     | 개인 라이브러리 여부  |
| startModeling | boolean |     | 즉시 렌더링 시작 여부 |
| {% endstep %} |         |     |              |

{% step %}

### 요청 보내기

```http
POST /api/v1/modelings
Content-Type: multipart/form-data
X-API-KEY: {x-api-key}

name=소파_모델링
file=@sofa.glb
```

{% endstep %}

{% step %}

### 응답 확인하기

생성에 성공하면 모델링 정보가 반환됩니다.

```json
{
  "result": "SUCCESS",
  "data": {
    "id": "mdl_abc123",
    "name": "소파_모델링",
    "userId": "usr_xyz",
    "renderingStatus": "WAITING",
    "dimension": {
      "mmWidth": 900,
      "mmDepth": 800,
      "mmHeight": 750,
      "inchWidth": 35.4,
      "inchDepth": 31.5,
      "inchHeight": 29.5
    },
    "images": [],
    "file": {
      "id": "ast_001",
      "name": "sofa.glb",
      "url": "https://..."
    },
    "createdAt": "2026-04-04T10:00:00Z",
    "updatedAt": "2026-04-04T10:00:00Z"
  }
}
```

`data.id` 값을 저장해두세요. 다음 단계인 [컴포넌트 생성](/dev/api-2/3d-product-integration/component.md)에 `modelingId`로 사용합니다.

{% hint style="info" %}
`renderingStatus`가 `WAITING`이면 렌더링이 아직 완료되지 않은 상태입니다. 렌더링이 완료되면 `renderAsset`에 결과물이 채워집니다.
{% endhint %}
{% endstep %}
{% endstepper %}

## 모델링 조회하기

**GET** `/api/v1/modelings/{id}`

생성된 모델링의 상태와 정보를 조회합니다.

```http
GET /api/v1/modelings/mdl_abc123
X-API-KEY: {x-api-key}
```

응답 구조는 모델링 생성 응답과 동일합니다.

## 모델링 파일 변경하기

**PATCH** `/api/v1/modelings/{id}/file`

기존 모델링의 3D 파일을 교체합니다. 요청은 `multipart/form-data` 형식으로 전송합니다.

| 필드            | 타입      |  필수 | 설명           |
| ------------- | ------- | :-: | ------------ |
| file          | file    |  ✅  | 새 3D 모델 파일   |
| startModeling | boolean |     | 즉시 렌더링 시작 여부 |

```http
PATCH /api/v1/modelings/mdl_abc123/file
Content-Type: multipart/form-data
X-API-KEY: {x-api-key}

file=@sofa_v2.glb
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archisketch.com/dev/api-2/3d-product-integration/modeling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.