Pinata API

访问 Pinata IPFS 存储 API。支持文件上传、群组管理、网关创建、签名添加、x402 支付配置，以及基于 AI 的向量搜索功能。

代码仓库：https://github.com/PinataCloud/pinata-api-skill

认证

所有请求均需携带以下请求头：

Authorization: Bearer $PINATA_JWT

环境变量：

• PINATA_JWT（必需）—— 您的 Pinata API JWT 令牌。可在 app.pinata.cloud/developers/api-keys 获取
• PINATA_GATEWAY_URL（必需）—— 您的 Pinata 网关域名（例如：your-gateway.mypinata.cloud）。可在 app.pinata.cloud/gateway 查看
• PINATA_GATEWAY_KEY（可选）—— 用于访问未绑定至您 Pinata 账户的公共 IPFS 内容的网关密钥。详见 Gateway Access Controls

测试认证

GET https://api.pinata.cloud/data/testAuthentication

基础 URL

• API：https://api.pinata.cloud
• 上传服务：https://uploads.pinata.cloud

通用参数

• {network} —— IPFS 网络类型：public（默认）或 private
• 分页使用 limit 和 pageToken 查询参数

文件

搜索文件

GET https://api.pinata.cloud/v3/files/{network}

查询参数（均为可选）：name、cid、mimeType、limit、pageToken

根据 ID 获取文件

GET https://api.pinata.cloud/v3/files/{network}/{id}

更新文件元数据

PUT https://api.pinata.cloud/v3/files/{network}/{id}
Content-Type: application/json

请求体：

{
  "name": "new-name",
  "keyvalues": {"key": "value"}
}

两个字段均为可选。

删除文件

DELETE https://api.pinata.cloud/v3/files/{network}/{id}

上传文件

POST https://uploads.pinata.cloud/v3/files
Content-Type: multipart/form-data

表单字段：

• file（必需）—— 待上传的文件
• network（可选）—— public 或 private
• group_id（可选）—— 将文件加入指定群组
• keyvalues（可选）—— JSON 格式的键值对元数据字符串

群组

列出群组

GET https://api.pinata.cloud/v3/groups/{network}

查询参数（均为可选）：name、limit、pageToken

创建群组

POST https://api.pinata.cloud/v3/groups/{network}
Content-Type: application/json

请求体：

{
  "name": "my-group"
}

获取群组

GET https://api.pinata.cloud/v3/groups/{network}/{id}

更新群组

PUT https://api.pinata.cloud/v3/groups/{network}/{id}
Content-Type: application/json

请求体：

{
  "name": "updated-name"
}

删除群组

DELETE https://api.pinata.cloud/v3/groups/{network}/{id}

将文件加入群组

PUT https://api.pinata.cloud/v3/groups/{network}/{groupId}/ids/{fileId}

从群组中移除文件

DELETE https://api.pinata.cloud/v3/groups/{network}/{groupId}/ids/{fileId}

网关与下载

创建私有下载链接

POST https://api.pinata.cloud/v3/files/private/download_link
Content-Type: application/json

为访问私有文件生成临时签名 URL。

请求体：

{
  "url": "https://{PINATA_GATEWAY_URL}/files/{cid}",
  "expires": 600,
  "date": 1700000000,
  "method": "GET"
}

• url（必需）—— 使用您的 PINATA_GATEWAY_URL 和文件 CID 构成的完整网关 URL
• expires（可选）—— 过期时间（单位：秒，默认为 600）
• date（必需）—— 当前 Unix 时间戳（单位：秒）
• method（必需）—— HTTP 方法，通常为 GET

创建签名上传 URL

POST https://uploads.pinata.cloud/v3/files/sign
Content-Type: application/json

生成客户端直传用的预签名 URL（客户端无需携带 JWT）。

请求体：

{
  "date": 1700000000,
  "expires": 3600
}

可选字段：max_file_size（字节数）、allow_mime_types（字符串数组）、group_id、filename、keyvalues

签名

使用 EIP-712 签名验证内容真实性。

添加签名

POST https://api.pinata.cloud/v3/files/{network}/signature/{cid}
Content-Type: application/json

请求体：

{
  "signature": "0x...",
  "address": "0x..."
}

获取签名

GET https://api.pinata.cloud/v3/files/{network}/signature/{cid}

删除签名

DELETE https://api.pinata.cloud/v3/files/{network}/signature/{cid}

按 CID 固定内容

通过 CID 固定已有 IPFS 内容（仅限 public 网络）。

固定一个 CID

POST https://api.pinata.cloud/v3/files/public/pin_by_cid
Content-Type: application/json

请求体：

{
  "cid": "bafybeig..."
}

可选字段：name、group_id、keyvalues、host_nodes（multiaddr 字符串数组）

查询固定请求

GET https://api.pinata.cloud/v3/files/public/pin_by_cid

查询参数（均为可选）：order（ASC/DESC）、status、cid、limit、pageToken

取消固定请求

DELETE https://api.pinata.cloud/v3/files/public/pin_by_cid/{id}

x402 支付指令

使用 x402 协议在 Base 链上以 USDC 对 IPFS 内容进行付费访问设置。

USDC 合约地址：

• Base 主网：0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Base Sepolia 测试网：0x036CbD53842c5426634e7929541eC2318f3dCF7e

注意：amount 字段使用 USDC 最小单位（6 位小数）。例如，$1.50 对应 "1500000"。

创建支付指令

POST https://api.pinata.cloud/v3/x402/payment_instructions
Content-Type: application/json

请求体：

{
  "name": "My Payment",
  "description": "Pay to access this content",
  "payment_requirements": [
    {
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "pay_to": "0xWALLET_ADDRESS",
      "network": "base",
      "amount": "1500000"
    }
  ]
}

• name（必需）—— 显示名称
• description（可选）—— 描述信息
• payment_requirements（必需）—— 数组，每项包含：asset（USDC 合约地址）、pay_to（收款钱包地址）、network（base 或 base-sepolia）、amount（最小单位，字符串格式）

列出支付指令

GET https://api.pinata.cloud/v3/x402/payment_instructions

查询参数（均为可选）：limit、pageToken、cid、name、id

获取支付指令

GET https://api.pinata.cloud/v3/x402/payment_instructions/{id}

删除支付指令

DELETE https://api.pinata.cloud/v3/x402/payment_instructions/{id}

关联 CID 与支付指令

PUT https://api.pinata.cloud/v3/x402/payment_instructions/{id}/cids/{cid}

解除 CID 与支付指令的关联

DELETE https://api.pinata.cloud/v3/x402/payment_instructions/{id}/cids/{cid}

向量化（AI 搜索）

为文件生成向量嵌入，并在群组范围内执行语义搜索。

向量化一个文件

POST https://uploads.pinata.cloud/v3/vectorize/files/{file_id}

删除文件向量

DELETE https://uploads.pinata.cloud/v3/vectorize/files/{file_id}

查询向量（语义搜索）

POST https://uploads.pinata.cloud/v3/vectorize/groups/{group_id}/query
Content-Type: application/json

请求体：

{
  "text": "search query here"
}

注意事项

• 所有 JSON 接口均需设置 Content-Type: application/json
• 文件上传接口使用 multipart/form-data —— 请勿手动设置 Content-Type
• 分页：使用上一次响应中的 pageToken 获取下一页数据
• 若未指定 network，默认为 public
• 网关 URL 格式为 https://{PINATA_GATEWAY_URL}/files/{cid}

资源

• Pinata 文档
• API 密钥
• 网关配置
• x402 协议
• 源码（GitHub）