> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-kr/api-sdk/api-integration/3d-product-integration/modeling.md).

# 모델링 등록하기

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

모든 API 요청 헤더에 `X-API-KEY`를 포함해야 합니다. 발급 방법은 [API 사용 방법](/guide/dev-kr/api-sdk/how-to-use.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` 값을 저장해두세요. 다음 단계인 [컴포넌트 생성](/guide/dev-kr/api-sdk/api-integration/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
```