Pinata の Files API v3 でグループ機能を使用する際のはまりポイントと解決策をまとめます。

背景

Pinata でアップロードしたファイルをグループで管理し、特定のグループに属するファイルのみを取得したいケースがあります。例えば、NFT登録フォームで使用する入力画像を「input」グループに格納し、そのグループからのみ画像を選択できるようにする場合などです。

はまりポイント

1. レガシーAPI と V3 API のファイル管理は分離されている

問題 : レガシーAPI（pinFileToIPFS）でアップロードしたファイルは、V3 API（/v3/files）では取得できません。逆も同様です。

レVガ3シーAAPPII(pvi3n/Lfiislte)s)→レガ→シーでVア3ッでプアロッープドロしーたドフしァたイフルァのイみル表の示み表示

解決策 : どちらかのAPIに統一する。V3 APIに移行する場合は、新規アップロードからV3を使用し、既存ファイルは手動でグループに追加するか、マイグレーションを検討。

2. V3 API のエンドポイントには {network} パラメータが必要

問題 : V3 API のエンドポイントは {network} パラメータ（public または private）が必須。

❌✅GGEETTv33//ffiilleess?/gpruobulpi=c{?ggrroouupp_=i{dg}roup_id}

解決策 : 通常のIPFSファイルには public を使用。

3. グループフィルタのパラメータ名が異なる

問題 : アップロード時とリスト取得時でパラメータ名が異なる。

操作パラメータ名
アップロードgroup_id
リスト取得group

4. JWT の種類による認証の違い

問題 : Scoped Key で生成した JWT は V3 API で動作しない場合がある。

解決策 : Pinata ダッシュボードで Admin 権限を持つ新しい API Key を生成。

実装例

環境変数

#P#PIIPNグNiAルAnTーTaAプAt_I_aJDIW（NJTPPW=iUTenTya_(JtGAhaRdbダOmGッUicシPniュ_権OボI限iーD推Jド=奨Iでb)U確6z認5I）413N3i7I2s-.d.a.dd-482d-9409-98e9c2e079ff

アップロード API（V3）

ice}moxpnpcccppppc)cr}aosooooiiiio;oe)prtrnnnnnnnn"{}ntsi;pttsssaaaashsuup/Itttttttttmh}btrcfa{Naaaaatee,oncspPsffpFFFFrptaAddeHiNUyoiiooooeshduyaNsa/eTnrlnrrrrs:oet:tesspx_cmeammmmpdrhax:hitGDtDDDD/:sopt:nRRfa=aaaaanu:ri=RtaeOutFttttsp"inerdtqUnafoaaaaelP{zaasuaauPcor....oOatwpet/e_t=rmaaaa=aStaao,ausIimDppppdTiFin.ptDoaDappppas"ootsdl,nwateeeew.,nreao=atannnnap:mr.taNPiaddddiiDejadepOt.=((((tn`ass./xrSg""""aBtpocrtoTrenfnngfteaonioRc(eteiaereaa,n(dueerq(wlmtot.rs{,tsseu"eewucceeepsqefF""ophlr..o.usio,,r_(ojtneetlrkiu$sssns.emff"dd{oevtf"Dii,"/pnV.:o)all,vr(3}Prtee"3o)でINmaa).pI/c;はfNeDs(;nuNferAxa)abPisdoTttF;mlUlsamARaieiTe.t_e(l)c_sea"Iq)e;"G"n.nNu;;)R,vdePe;O.axUsUPttTtPIa/_)_N.sGIAceR{DVTirO)3AdvU;_ePアJr_ッW"IプT;Dロ};必グー`須ルド,ーエプンにド追ポ加イント

リスト取得 API（V3）

ice}moxpnpccuuc}ccr}aosooorro)ooe)prtrnnllnmh};nntsi};pttsVs..see,sVsuum)/It3tssttaAt3trcainds)a{Naeehduncgpaai,pPslエuaaroetdレfeefmtziNUyiンrrredrhaスiNssseee/eTnmドlccs:sotポles:H:P:px_ciポhhp:raンex:aiitGtイ=PPo"iスstfsfnfnRRfンaanG{z=構RtihiniaeOu=トnrrsEa造=erl:leltqUn（eaaeTtasueedeauPcr/wmm"iwdpesf.:./e_tepss=,oaao,.inslsIiquU..nitnmlafiitDoubRssa:tasaemizs,nelLeew.ep.elet=si(tta`rd.(c,e,/NGtc"((iBeaj(i.repE.h""testsfdcoxrTnがtglapaoi,ruto(e必trifro?nletRcrx須pomeen.(eaeeeet）suitrsf{)t.ssqU:ptceietpsur/""h$.l=dso.el/,,({je>_nes.aupssasntspIlrro(tev:eiNilon{,.a.Pm.c(}PNrpUite)IeciTtos;[fNxhn_)Ss]rAtPaG;t.;oTRatRremAeraOin_qa.Unv"IumcPg.nNesl_(PePs.oI)IxUtguD,NtT)ed)A/_t/;{TsG{(vAeR"3_rOl/JvUifWePmiTr_ilg}"Iter`;D"s,;)uppu_bild"i5cで0"は")な;;くgroup

V3 API エンドポイント一覧

操作メソッドエンドポイント
ファイルアップロードPOSThttps://uploads.pinata.cloud/v3/files
ファイルリストGEThttps://api.pinata.cloud/v3/files/{network}
グループ作成POSThttps://api.pinata.cloud/v3/groups/{network}
グループにファイル追加PUThttps://api.pinata.cloud/v3/groups/{network}/{group_id}/ids/{file_id}

グループIDの確認方法

Pinata ダッシュボードでグループを選択すると、URLにグループIDが表示されます：

https://app.pinata.cloud/ipfs/groups/b6こ5れ4が3グ3ル7ー2プ-IdDadd-482d-9409-98e9c2e079ff

または、V3 API でファイルを取得すると、各ファイルの group_id フィールドで確認できます：

{}"}da"]tfai{}"l:e""""sincg{"dair:"mdo:e"u[":p":_0"i1"bd9ea"bxf:5ayfmb"8peb0li6-e.5c..42j.39p"38g,7-"27,-dd6afd-d9-f4f802-d5-89b420e91-69b8fec93c82"e,079ff"

デバッグのコツ

  1. まずグループフィルタなしでリスト取得 : ファイルが存在するか確認
  2. レスポンスのgroup_id を確認: 期待するグループに属しているか確認
  3. エンドポイントURLを確認 : /public や /private が含まれているか確認

まとめ

項目レガシーAPIV3 API
アップロードapi.pinata.cloud/pinning/pinFileToIPFSuploads.pinata.cloud/v3/files
リストapi.pinata.cloud/data/pinListapi.pinata.cloud/v3/files/{network}
グループパラメータ（アップロード）なしgroup_id
グループパラメータ（リスト）groupIdgroup
CIDの取得response.IpfsHashresponse.data.cid

V3 API への移行時は、これらの違いに注意して実装してください。