에셋 및 메타데이터 업로드
Metadata API는 Klaytn의 KIP-17 토큰 (NFT, Non-Fungible Token)와 KIP-37 토큰 (MT, Multi Token) 발행 시 에셋(asset)과 메타데이터(metadata)를 업로드, 관리하는 기능을 제공합니다.
이 예제에서는 Metadata API를 에셋과 메타데이터을 업로드하는 방법에 대해 설명하겠습니다.
에셋 업로드
에셋이란 NFT나 MT가 가지고 있는 그림, 영상 등을 지칭하며, 토큰 정보에 파일 형태(jpg, gif, png 등)로 저장됩니다. NFT나 MT 발행시 우선 에셋을 업로드하고, 결과값으로 나오는 에셋의 URI를 메타데이터에 포함시켜 발행합니다.
API 요청
Metadata API의
POST/v1/metadata/asset 엔드포인트로 요청을 보내 에셋을 업로드할 수 있습니다.에셋을 업로드 하기 위한 cURL 코드는 아래와 같습니다.
1
curl --location --request POST 'https://metadata-api.klaytnapi.com/v1/metadata/asset' \
2
--header 'x-chain-id: 8217' \
3
--header 'Authorization: Basic S0FTS0U0Mjc5Q01VMVhLVDg1UTRBVkRBOlFEMENMam5XRW94TzZfQ3pYLV9oLWRrQkZnMDVxR1FnbWlYcDAwVno=' \
4
--form '[email protected]"/Users/usernamed/Documents/files/1kbfile.jpg"'
Copied!
각 부분에 대한 설명은 다음과 같습니다:
- POST 'https://metadata-api.klaytnapi.com/v1/metadata/asset': 각각 POST 메서드와 요청이 전송될 엔드포인트를 나타냅니다.
- x-chain-ID: Metadata API는
x-chain-id헤더값을 요구합니다. 허용되는 값은 1001(Baobab), 8217(Cypress) 입니다. - Authorization: KAS는 Basic HTTP Auth를 사용합니다. 모든 요청은 반드시 올바른 Authorization 헤더를 가져야 하며 KAS 사용자는
access key ID를username으로,secret access key를password로 사용합니다. - Form: 업로드할 파일의 위치입니다. 파일은 10MB를 초과해선 안됩니다.
에셋에 접근할 수 있는 URL의 유효성 여부는 따로 검증하지 않기 때문에, 여러분이 직접 확인해야 합니다.
API 응답
에셋 업로드
curl을 수행하면 다음과 같은 결과를 받게 됩니다.1
{
2
"filename": "4a85e6be-3215-93e6-d8a9-3a7d633584e7.png",
3
"contentType": "image/png",
4
"uri": "https://metadata-store.klaytnapi.com/e2d83fbb-c123-811c-d5f3-69132v482c51/4a85e6be-3215-93e6-d8a9-3a7d633584e7.png"
5
}
Copied!
- File Name: 에셋에 자동으로 부여되는 고유의 식별값이 파일 이름으로 반환됩니다.
- Content Type: 요청 형식을 나타내며, 위 예시의 경우 png 이미지 파일입니다.
- URI: 메타데이터가 저장된 외부 접근 가능 URI입니다. https://example.com/{storage-ID}/{asset-ID}.png 형식으로 구성되어 있습니다. Storage ID는 각 유저에게 부여되는 고유의 식별값이며, Asset ID는 각 에셋에 자동으로 부여되는 식별값입니다.
업로드가 정상적으로 처리되었는지 확인하기 위해서 반환되는 URI에 접근하여 올바른 에셋이 업로드 됐는지 확인하시기 바랍니다.
메타데이터 업로드
메타데이터란 본래 "데이터에 대한 데이터"를 의미하는데, KIP-17 토큰이나 KIP-37 토큰의 경우 토큰의 속성(이름, 설명, 이미지 URL 등)을 메타데이터라고 칭합니다. JSON 파일 형식으로 저장됩니다.
API 요청
Metadata API의
POST/v1/metadata 엔드포인트로 요청을 보내 메타데이터를 업로드할 수 있습니다.1
{
2
"metadata": {
3
"name": "Kitty Heaven NFT",
4
"description": "This is a sample description",
5
"image": "https://metadata-store.klaytnapi.com/e2d83vdb-c108-823c-d5f3-69vdf2d871c51/4a85e6be-3215-93e6-d8a9-3a7d633584e7.png"
6
},
7
"filename": "haha.json"
8
}
Copied!
각 필드에 대한 설명은 다음과 같습니다:
- Name: 토큰의 이름입니다.
- Description: 토큰에 대한 설명입니다.
- Image: 토큰 이미지가 저장된 외부 접근 가능 URI입니다.
- File Name: 필수값은 아닙니다. 원하는 경우 반환되는 파일 이름을 지정할 수 있습니다. 확장자는
.json이어야 합니다.
API 응답
1
{
2
"filename": "haha.json",
3
"contentType": "application/json",
4
"uri": "https://metadata-store.klaytnapi.com/e2d83vdb-c108-823c-d5f3-69vdf2d871c51/haha.json"
5
}
Copied!
- File Name: 파일 이름을 지정한 경우 반환됩니다.
- Content Type: 요청 형식을 나타내며, 위 예시의 경우 JSON입니다.
- URI: 메타데이터가 저장된 외부 접근 가능 URI입니다. https://example.com/{storage-ID}/{file-name} 형식으로 구성되어 있습니다. Storage ID는 각 유저에게 자동으로 부여되는 값입니다.
업로드가 정상적으로 처리되었는지 확인하기 위해서 반환되는 URI에 접근하여 올바른 메타데이터가 업로드 됐는지 확인하시기 바랍니다.
Last modified 14d ago