> For the complete documentation index, see [llms.txt](https://docs.chiliz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chiliz.com/ko/gaebal/goseup/nft-jageob/ipfs-nft-hoseuteing.md).

# IPFS에 NFT 호스팅

NFT를 보유한다는 것이 NFT 파일이 블록체인에 그대로 업로드된다는 것을 의미하지 않습니다.\
실제로 NFT는 특정 토큰을 포함하는 블록체인 블록에 해당합니다. 이 토큰은 `tokenURI`라고 하는 "포인터" 또는 링크를 저장하는데, 이것은 메타데이터 파일의 온라인 주소를 담고 있으며, 메타데이터 파일 자체는 다른 URI를 사용하여 미디어 파일을 참조합니다.

블록체인의 P2P 특성상 NFT 파일과 메타데이터 파일을 일반 웹 호스팅 서비스에 호스팅할 수 없습니다. `tokenURI`는 가능한 한 오래, 영원히 앱과 마켓플레이스 간에 영구적(또는 "불변")이고 이식 가능한 상태로 유지되어야 합니다.

바로 이 점에서 IPFS가 등장합니다.

## **IPFS 소개**

[IPFS](https://ipfs.tech/)(InterPlanetary File System)는 분산 네트워크 전반에 걸쳐 데이터를 호스팅하고 공유하는 목적으로 설계된 탈중앙화 파일 네트워크입니다. NFT 플랫폼은 단일 서버에 의존하는 대신 IPFS에서 데이터를 가져올 수 있으며, IPFS 프로토콜은 호스팅된 모든 파일이 로컬에 있는 것처럼 느껴지게 합니다.

{% hint style="success" %}
**지금 당장 IPFS를 배워야 할까요?**

이는 NFT를 민팅하는 방법에 따라 다릅니다:

* 바닐라 코드(예: [viem](https://viem.sh/) 또는 [ethers](https://ethers.org/)) 사용 시:\
  **예**, 사전에 유효한 `tokenURI`(예: `ipfs://.../metadata.json`)가 필요합니다.
* [thirdweb](https://thirdweb.com/)과 같은 대시보드 사용 시:\
  **아니요**. IPFS 업로드가 내장되어 있습니다. NFT 파라미터에 기존 `ipfs://...`가 있다면 붙여넣기도 가능합니다.
* [Rarible의 Multichain SDK](https://docs.rarible.org/reference/getting-started)와 같은 대부분의 Web3 SDK 사용 시:\
  **예**, URI가 필요합니다. 일부 도구는 업로드를 도와줄 수 있지만 대부분은 그렇지 않습니다.
  {% endhint %}

IPFS 웹사이트에는 [NFT 저장 모범 사례에 관한 상세 페이지](https://docs.ipfs.tech/how-to/best-practices-for-nft-data/#types-of-ipfs-links-and-when-to-use-them)가 있습니다.

## NFT 업로드 세부사항

NFT를 업로드할 때, IPFS가 생성하는 CID(Content Identifier)에 두 가지 업로드를 수행해야 합니다:

* 콘텐츠 자체 — IPFS가 호스팅된 파일에 대한 IPFS URL을 반환합니다.
* 메타데이터 파일 — 미디어 파일의 CID를 참조하며, 파일에 대한 IPFS URL을 포함해야 합니다.

두 파일 모두 동일한 CID 아래 IPFS에 업로드되어야 합니다.

이상적으로는 사용 중인 도구가 이 과정을 대신 처리해 주어 수동으로 모든 작업을 할 필요가 없습니다.

참고용으로, 최소한의 `metadata.json` 파일이 어떻게 생겼는지 보여드립니다:

```json
{ 
    "name": "Stadium Pass #25456456", 
    "description": "PSG supporter entry ticket", 
    "image": "ipfs:///filename.png",           // for static images only!
    // "animation_url": "ipfs:///filename.mp4" // for video and audio files.
    "attributes": [
    { 
        "trait_type": "Tier", 
        "value": "Gold" 
    }] 
}
```

NFT 메타데이터 구조에 대해 더 알고 싶다면(예: 이미지에는 `image`를, 동영상에는 `animation_url`을 사용해야 하는 이유 등), OpenSea의 다음 문서를 읽어보시기 바랍니다:

{% embed url="<https://docs.opensea.io/docs/metadata-standards#metadata-structure>" %}

참고: *메타데이터 파일을 처음부터 직접 작성할 필요가 없습니다!*\
사용 중인 도구가 자동으로 생성해 줄 것입니다.

{% hint style="success" %}
[직접 IPFS 노드를 실행](https://docs.ipfs.tech/how-to/command-line-quick-start/)하거나, 필요에 따라 무료 요금제를 제공하는 [Pinata](https://pinata.cloud/) 같은 IPFS 호스팅 서비스를 이용할 수 있습니다.

[Pinata의 빠른 시작 가이드](https://docs.pinata.cloud/quickstart)를 따라 API 자격증명(API 키, API 시크릿, JWT 토큰)과 전용 게이트웨이 도메인(예: `blue-genetic-quail-122.mypinata.cloud`)을 발급받으세요.
{% endhint %}

이 문서는 IPFS에 대한 모든 것을 설명하기 위한 것이 아니므로, 온라인 검색을 통해 이 주제를 더 깊이 탐구하시기 바랍니다. 다음 Pinata 설명 자료로 시작할 수 있습니다:

{% embed url="<https://docs.pinata.cloud/ipfs-101/how-does-ipfs-work-with-nfts>" %}

... 또는 thirdweb의 블로그 포스트:

{% embed url="<https://blog.thirdweb.com/guides/securing-pinning-your-nft-with-ipfs/>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.chiliz.com/ko/gaebal/goseup/nft-jageob/ipfs-nft-hoseuteing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.