에셋 및 메타데이터 업로드

에셋과 메타데이터는 Klaytn의 대체불가토큰 기술표준인 KIP-17 토큰(NFT), Klaytn의 멀티토큰 기술표준인 KIP-37 토큰(MT)을 발행할 때 사용합니다.

이 예제에서는 Metadata API를 이용하여 에셋과 메타데이터를 업로드하는 방법에 관해 설명하겠습니다.
에셋과 메타데이터를 저장하는 Storage에 관한 설명은 Metadata API에서 확인하세요.

에셋 업로드

에셋이란 NFT나 MT가 가지고 있는 그림, 영상 등을 지칭하며, 토큰 정보에 파일 형태(jpg, gif, png 등)로 저장됩니다. NFT나 MT 발행시 우선 에셋을 업로드하고, 결과값으로 나오는 에셋의 URI를 메타데이터에 포함시켜 발행합니다.

API 요청

Metadata API의 POST/v1/metadata/asset 엔드포인트로 요청을 보내 에셋을 업로드할 수 있습니다.

에셋을 업로드 하기 위한 cURL 코드는 아래와 같습니다.

curl --location --request POST 'https://metadata-api.klaytnapi.com/v1/metadata/asset' \
--header 'x-chain-id: 8217' \
--header 'Authorization: Basic S0FTS0U0Mjc5Q01VMVhLVDg1UTRBVkRBOlFEMENMam5XRW94TzZfQ3pYLV9oLWRrQkZnMDVxR1FnbWlYcDAwVno=' \
--form 'file=@"/Users/usernamed/Documents/files/1kbfile.jpg"'

caver.initMetadataAPI(chainId, accessKeyId, secretAccessKey, url);
const filepath = fpath.join(__dirname, "../fixture/img-png.png");
const file = fs.createReadStream(filepath);

const ret = await caver.kas.metadata.uploadAsset(file); // file upload
const ret = await caver.kas.metadata.uploadAsset(file, krn); // storage krn setting
const ret = await caver.kas.metadata.uploadAsset(file, callback); // callback call

각 부분 설명은 다음과 같습니다.

• 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를 초과해선 안됩니다.

API 응답

에셋 업로드 curl을 수행하면 다음과 같은 결과를 받게 됩니다.

{
  "filename": "4a85e6be-3215-93e6-d8a9-3a7d633584e7.png",
  "contentType": "image/png",
  "uri": "https://metadata-store.klaytnapi.com/e2d83fbb-c123-811c-d5f3-69132v482c51/4a85e6be-3215-93e6-d8a9-3a7d633584e7.png"
}

• File Name: 에셋에 자동으로 부여되는 고유의 식별값이 파일 이름으로 반환됩니다.
• Content Type: 요청 형식을 나타내며, 위 예시의 경우 png 이미지 파일입니다.
• URI: 메타데이터가 저장된 외부 접근 가능 URI입니다. https://example.com/{storage-ID}/{asset-ID}.png 형식으로 구성되어 있습니다. Storage ID는 각 유저에게 부여되는 고유의 식별값이며, Asset ID는 각 에셋에 자동으로 부여되는 식별값입니다.

반환되는 URI에 접근하여 올바른 에셋이 업로드됐는지 확인하시기 바랍니다.

KAS Console에서 Asset 목록 확인하기

Metadata API를 활용해 업로드한 에셋 내역은 KAS Console에서도 확인할 수 있습니다. 확인 방법은 다음과 같습니다.

1. KAS Console에 접속하여 로그인합니다.

2. KAS Console > [Service] > [Metadata] > [Storage] 메뉴에서 해당 storage를 선택합니다.

3. Storage 상세정보 Asset 탭에서 업로드한 에셋 내역을 확인합니다.
Asset URI를 클릭하면 에셋 원본을 확인할 수 있습니다.

메타데이터 업로드

메타데이터란 '다른 데이터를 설명하는 데이터'를 의미합니다. KIP-17 혹은 KIP-37 토큰에서 의미하는 메타데이터는 이름, 설명, 이미지 URL 등 토큰의 속성을 포함합니다. JSON 파일 형식으로 저장됩니다.

각 플랫폼에 따른 프로퍼티 종류와 적용사례는 메타데이터 규격에서 확인하세요.

API 요청

Metadata API의 POST/v1/metadata 엔드포인트로 요청을 보내 메타데이터를 업로드할 수 있습니다.

{
  "metadata": {
      "name": "Kitty Heaven NFT",
      "description": "This is a sample description",
      "image": "https://metadata-store.klaytnapi.com/e2d83vdb-c108-823c-d5f3-69vdf2d871c51/4a85e6be-3215-93e6-d8a9-3a7d633584e7.png"
  },
  "filename": "haha.json"
}

const metadata = {
  name: "Puppy Heaven NFT",
  description: "This is a sample description",
  image: "https://....png",
};
caver.initMetadataAPI(chainId, accessKeyId, secretAccessKey, url);
const ret = await caver.kas.metadata.uploadMetadata(metadata); // upload metadata
const ret = await caver.kas.metadata.uploadMetadata(metadata, filename); // set file name
const ret = await caver.kas.metadata.uploadMetadata(metadata, krn); // set storage
const ret = await caver.kas.metadata.uploadMetadata(metadata, filename, krn);
const ret = await caver.kas.metadata.uploadMetadata(metadata, callback); // set callback

각 필드 설명은 다음과 같습니다.

• Name: 토큰의 이름입니다.
• Description: 토큰 설명입니다.
• Image: 토큰 이미지가 저장된 외부 접근 가능 URI입니다.
• File Name: 필수값은 아닙니다. 원하는 경우 반환되는 파일 이름을 지정할 수 있습니다. 확장자는 .json 이어야 합니다.

API 응답

{
  "filename": "haha.json",
  "contentType": "application/json",
  "uri": "https://metadata-store.klaytnapi.com/e2d83vdb-c108-823c-d5f3-69vdf2d871c51/haha.json"
}

• File Name: 파일 이름을 지정한 경우 반환됩니다.
• Content Type: 요청 형식을 나타내며, 위 예시의 경우 JSON입니다.
• URI: 메타데이터가 저장된 외부 접근 가능 URI입니다. https://example.com/{storage-ID}/{file-name} 형식으로 구성되어 있습니다. Storage ID는 각 유저에게 자동으로 부여되는 값입니다.

자세한 내용은 KAS Reference Documentation의 Metadata API를 확인하십시오.
이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.