mint-api

Mint API

Mint の本番 API を、アカウント所有のアセットパイプラインとして使用します。

安全に開始する

1. references/quickstart.md を読みます。
2. 現在の公開ドキュメントの概要があると便利な場合は、https://docs.mint.gg/llms.txt を取得します。複数のガイドにわたる広範なコンテキストが必要な場合に限り、https://docs.mint.gg/llms-full.txt を取得します。
3. 不慣れなエンドポイントやフィールドを使用する前に、本番の OpenAPI コントラクト https://api.mint.gg/openapi.json を読みます。これは、正確なエンドポイントとスキーマの信頼できる情報源です。
4. 環境変数から MINT_API_KEY を読み込みます。表示、貼り付け、無関係なサービスへの送信、コミットは決して行わないでください。
5. ライブの ID および Credits の確認についてユーザーから許可を得た場合に限り、node scripts/check-connection.mjs を実行します。

ワークフロー

1. サービスと fast／standard／production プリセットを選択します。推奨される auto ワークフローを使用するには generationMode を省略します。統合で Preview に関する判断が必要な場合に限り、review を選択します。
2. 生成を開始します。ユーザーが Mint に表示する特定のタイトルを希望する場合に限り、name を使用します。
3. 返された操作 ID を保存します。操作によってアセットが作成される場合は、operation.resource からそのタイプと ID を読み取ります。
4. 上限付きの指数バックオフで操作の状態を確認します。scripts/poll-operation.mjs または同等のアプリケーションロジックを使用します。
5. review モードでは preview_ready の時点で停止し、ユーザーの意図に沿った判断がある場合に限り、承認または修正を行います。
6. partially_succeeded を含む、すべての終了ステータスに対応します。
7. アセットを取得し、ファイル URL を推測するのではなく、マニフェストを通じてファイルを確認します。

サービスのワークフローとレビュー操作については references/service-workflows.md を、アセットの配信については references/assets-and-files.md を読みます。

不変条件

• API で作成されたリソースは Mint アカウントに属し、API、MCP、Mint を通じて表示される場合があります。
• World、3D Model、Asset Pack の生成では、imageUrl ひとつ、または sourceImages 2～8 件のいずれかを指定します。両方を指定することはできません。Materials と Material Packs が使用できるのは、imageUrl ひとつだけです。
• Asset Pack は自然言語の prompt を指定して開始します。Mint が個々のアセットと共通のスタイルを計画します。正確な制御が必要な場合に限り、任意の itemCount、assetPackType、styleGuide を使用します。数が指定されておらず、プロンプトにも記載されていない場合、Mint は 8 個のアセットを作成します。適合する専用タイプがない場合、Mint は general_asset_pack を使用します。
• riggingPose: "t_pose" | "a_pose" は 3D Models と Asset Packs に限り使用します。後からリギングできるよう、全身が正面を向き、手に何も持っていないヒューマノイドの Preview を準備します。アセットのリギングやアニメーションは行いません。
• アカウント所有の 3D Model は POST /v1/models/{modelId}:convert で変換します。リクエストボディには要求されたフォーマットと任意の名前のみを指定します。外部ソース URL は決して送信しないでください。
• プロバイダーのモデル ID は公開コントラクトに含まれません。公開プリセットを指定します。
• totalReserved、monthlyReserved、topUpReserved は、確定した支出ではなく保留中の Credits として扱います。
• 操作が billing_required を報告した場合は、その課金アクションを表示し、操作 ID を保持します。課金が解決された後、Preview または中間リソースがある操作は再開します。リソースが作成されていない場合は、同じ Idempotency-Key を使って元のリクエストを再試行します。
• ポーリング、再試行、バッチサイズ、総コストには上限を設けます。Retry-After に従います。Mint では、認証済みリクエストは毎分 600 件、有料作業の開始はアカウントごとに毎分 30 件までで、アカウント内のすべての API キーで共有されます。
• 通常の変更リクエストでは Idempotency-Key を省略します。統合で結果が不確かな変更リクエストを再試行する場合は、最初の試行前に安定したキーをひとつ生成し、そのリクエストの再試行に限って再利用します。
• 内部 URL、ローカルテスト用キー、プロバイダーの認証情報、非公開ドキュメント、実装専用のモデル ID は決して公開しないでください。
• API キーをブラウザーやモバイルのクライアントに置かないでください。信頼できるサーバーコードから Mint を呼び出します。

エラー処理を設計する前に references/errors-and-retries.md を読みます。