NFT Metadata Standards

이 페이지에서는 Klip에서 사용하는 NFT 메타데이터 속성의 표준을 설명합니다. 이 표준에 정의되지 않은 속성과 형식의 경우 Klip 내에서 정상적으로 노출되지 않을 수 있으니 참고 바랍니다.

메타데이터 속성
Klip에서 지원하는 속성값의 이름과 설명은 다음과 같습니다. OpenSea에서 사용하는 속성값과 일부 명칭 차이가 있으니 유의 바랍니다.
이름
타입
설명
name*
string
NFT 이름입니다.
description*
string
NFT에 관한 설명입니다.
image*
string
NFT에 사용할 이미지 URL 주소입니다. 이미지 파일 형식이 아니거나 경로에 확장자가 포함되지 않는 경우 정상적으로 표시되지 않을 수 있습니다.
animation_url
string
NFT에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 .mp4입니다. H.264 코덱이 아니거나 해상도가 3840x2160을 넘는 경우 재생되지 않을 수 있습니다.
background_color
string
NFT 이미지 배경에 사용할 RGB 색상 코드입니다. # 다음에 16진수 6자리 문자열로 표시합니다.
sendable
boolean
TRUE이면 해당 NFT를 Klip에서 다른 사람에게 전송할 수 있습니다. 지정되지 않은 경우 기본값은 TRUE입니다.
group_name
string
NFT를 그룹핑할 때 사용하는 그룹 이름입니다.
group_icon
string
NFT를 그룹핑할 때 그룹 아이콘으로 사용할 이미지 URL 주소입니다.
hashtags
array
해시태그들이 담긴 string 배열입니다. 해시태그를 달면 Klip 내에서 NFT를 검색하는데 활용됩니다.
layout
string
NFT 이미지를 보여주는 방식입니다. 정사각형 이미지는 general, 가로가 더 긴 이미지는 horizontal, 세로가 긴 이미지는 vertical로 설정할 수 있습니다. 지정되지 않은 경우 기본값은 general입니다.
external_link
string
Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
external_url
string
Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
custom_links
array
Klip 외부로 연결되는 URL 주소들이 담긴 object 배열 입니다. display_name에 노출할 속성명, value에 속성값을 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255)
qr_code
string
QR Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
bar_code
string
Bar Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
attributes
array
NFT의 속성값들이 담긴 object 배열입니다. trait_type으로 노출할 속성명, value로 속성값을 쌍을 이뤄 지정합니다.
status_url
string
NFT의 상태 정보를 담고 있는 외부 URL 주소입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 valid 필드와 선택적으로 array type의 attributes 필드를 설정할 수 있습니다.
has_secure_metadata
boolean
TRUE이면 Klip에서 NFT의 소유자만 볼 수 있는 정보를 담고 있다는 의미입니다. 해당 기능을 사용하려면 Klip Partners를 통해 NFT를 발행해야 하며, 외부에서 NFT를 직접 발행하는 경우에는 해당 기능을 이용할 수 없습니다.
token uri에 data:application/json 으로 시작하는 data uri를 지정하는 경우, 일부 화면에서 정상적으로 처리되지 않을 가능성이 있고 1024자 이상은 지원되지 않습니다. 가능하면 http 또는 https URL을 사용하는 것을 권해드립니다.
권장 이미지 및 영상 규격
Klip에 노출되는 NFT 이미지와 영상은 각각 권장 규격과 파일 형식이 존재합니다. 아래 기준을 따르지 않는 경우 NFT 이미지 또는 영상이 정상적으로 표시/재생되지 않을 수 있습니다.
이미지 규격
최소 크기: 1024px x 1024px 이상
최대 크기: 23170px x 23170px 이하
용량: 5MB 이하
확장자: JPG, JPEG, GIF, PNG 등 이미지 파일 확장자 (동영상 형식 미지원)
해상도: 72dpi 이상
영상 규격
최대 크기: 가로 3840px, 세로 2160px 이하
용량: 50MB 이하
확장자: MP4
동영상 코덱: H.264
오디오 코덱: AAC
레터박스는 영상에 포함하지 않는 것을 권장
구조와 예시
Klip에서 지원하는 속성에 맞춰 작성된 메타데이터의 예시는 아래와 같습니다.
{
    "name": "Magic Sword",
    "description" : "You can summon a demonic sword with a magic attribute.",
    "image": "https://media.klipwallet.com/card_asset/163632/c6525c6e-060c-426f-9275-0dabadb0ba97.png",
    "background_color" : "#ffffff",
    "sendable": true,
    "group_name": "Weapon",
    "group_icon": "https://media.klipwallet.com/temp_eventcard/bomb_klip.jpg",
    "hashtags": ["Game","GroundX","Magic"],
    "layout": "general",
    "external_link": "https://gxmagicgame.com",
    "attributes" : [
        {
            "trait_type": "Sword", 
            "value": "Iron Short Sword"
        }, 
        {
            "trait_type": "Magic Type", 
            "value": "Fire"
        }, 
        {
            "trait_type": "Sword Level", 
            "value": "5"
        }, 
        {
            "trait_type": "Magic Level", 
            "value": "2"
        }
      ],
    "status_url" : "https://fakeapi.gx.com/itemstatus?item_id=923874829"
}
여기에서 status_url에 지정된 URL 주소를 통한 응답값 예시는 아래와 같습니다.
{
    "valid": true,
    "attributes": [
        {
            "trait_type": "VIP Membership",
            "value": "Applicable"
        },
        {
            "trait_type": "Expiration Date",
            "value": "2023-12-31"
        }
    ]
}
위의 예시 메타데이터로 발행한 NFT가 Klip에서 어떻게 보이는지 살펴보겠습니다.
NFT예시이미지1
먼저 메타데이터에 포함된 image 파일이 NFT 대표 이미지로 나타나고, 그 아래로 name과 description이 표시됩니다. animation_url을 추가하여 동영상이 있는 경우에도 image는 필수 값으로, 여기에 지정된 이미지가 대표 이미지로 표시되고 동영상은 대표 이미지를 클릭해 확인할 수 있습니다.
NFT예시이미지2
그 하단에 group_icon과 group_name 정보가 표시됩니다. 그룹이 지정되면 콜렉션 내의 NFT 목록에서 상단에 필터 메뉴가 표시되어 빠른 분류 및 검색이 가능합니다. 한편 status_url로 동적 정보가 지정된 경우, 그 상태값과 속성을 실시간으로 가져와 NFT 정보에 보여줍니다.
NFT예시이미지3
그 하단으로 attributes를 통해 지정한 세부 속성값이 trait_type - value 쌍으로, external_link를 통해 지정한 URL이 클릭 가능한 외부 링크로, hashtags를 통해 지정한 해시태그 값들이 #가 자동으로 붙어 표시됩니다. 아울러 본 NFT는 sendable이 true로 지정되어있기 때문에 "보내기" 버튼이 활성화되어 노출됩니다. 그 이하로 표시되는 내용들은 NFT의 수신 내역과 콜렉션에 대한 정보들로, 메타데이터와 직접적으로 관련 있는 내용은 아닙니다.
이렇게 외부에서 Klip의 표준에 맞춰 구성된 메타데이터가 Klip UI 상 어떻게 표시되는지 알아보았습니다. 본 스크린샷은 환경에 따라, 또는 추후 Klip UI 개선/변경에 따라 다소 차이가 발생할 수 있습니다.
이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.

이름	타입	설명
name*	string	NFT 이름입니다.
description*	string	NFT에 관한 설명입니다.
image*	string	NFT에 사용할 이미지 URL 주소입니다. 이미지 파일 형식이 아니거나 경로에 확장자가 포함되지 않는 경우 정상적으로 표시되지 않을 수 있습니다.
animation_url	string	NFT에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 .mp4입니다. H.264 코덱이 아니거나 해상도가 3840x2160을 넘는 경우 재생되지 않을 수 있습니다.
background_color	string	NFT 이미지 배경에 사용할 RGB 색상 코드입니다. # 다음에 16진수 6자리 문자열로 표시합니다.
sendable	boolean	TRUE이면 해당 NFT를 Klip에서 다른 사람에게 전송할 수 있습니다. 지정되지 않은 경우 기본값은 TRUE입니다.
group_name	string	NFT를 그룹핑할 때 사용하는 그룹 이름입니다.
group_icon	string	NFT를 그룹핑할 때 그룹 아이콘으로 사용할 이미지 URL 주소입니다.
hashtags	array	해시태그들이 담긴 `string` 배열입니다. 해시태그를 달면 Klip 내에서 NFT를 검색하는데 활용됩니다.
layout	string	NFT 이미지를 보여주는 방식입니다. 정사각형 이미지는 `general`, 가로가 더 긴 이미지는 `horizontal`, 세로가 긴 이미지는 `vertical`로 설정할 수 있습니다. 지정되지 않은 경우 기본값은 `general`입니다.
external_link	string	Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
external_url	string	Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
custom_links	array	Klip 외부로 연결되는 URL 주소들이 담긴 `object` 배열 입니다. `display_name`에 노출할 속성명, `value`에 속성값을 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255)
qr_code	string	QR Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
bar_code	string	Bar Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
attributes	array	NFT의 속성값들이 담긴 `object` 배열입니다. `trait_type`으로 노출할 속성명, `value`로 속성값을 쌍을 이뤄 지정합니다.
status_url	string	NFT의 상태 정보를 담고 있는 외부 URL 주소입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 `valid` 필드와 선택적으로 array type의 `attributes` 필드를 설정할 수 있습니다.
has_secure_metadata	boolean	TRUE이면 Klip에서 NFT의 소유자만 볼 수 있는 정보를 담고 있다는 의미입니다. 해당 기능을 사용하려면 Klip Partners를 통해 NFT를 발행해야 하며, 외부에서 NFT를 직접 발행하는 경우에는 해당 기능을 이용할 수 없습니다.

Design Guidelines

Change Log

Last modified 2mo ago