lowpoly は 2026/10/30 に廃止されます。 3D 生成モデルとしての meshy-7 は 2026/12/31 に廃止されます。テクスチャモデルとしては引き続き利用できます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

Usage API

チームで完了したAPIタスクと、各タスクで消費したクレジットを一覧表示します。請求のエクスポートやコストレポートにご利用ください。

このエンドポイントを呼び出すには、StudioまたはEnterpriseチームの有効なメンバーのAPIキーを使用してください。オーナーや管理者に限らず、どのメンバーでも呼び出せます。それ以外のAPIキーでリクエストすると、403が返されます。


GET/openapi/v1/usage/tasks

使用状況レコードの一覧取得

チームの使用状況レコードを1ページ分返します。デフォルトでは新しい順です。start_timeとend_timeを指定しない場合、レコードは過去30日分が対象になります。このエンドポイントの呼び出しは無料です。

レコードには次のタスクが含まれます。

  • SUCCEEDEDまたはFAILEDで終了したAPIタスク
  • チームの現在のすべてのメンバーのタスク(どのAPIキーからのものでも)
  • 削除済みのタスクや、ファイルの有効期限が切れたタスク

レコードには次のタスクは含まれません。

  • まだPENDINGまたはIN_PROGRESSのタスク、およびCANCELEDのタスク
  • チームを離脱した人のタスク
  • Creative Labのタスク
  • MeshyのAIエージェントが実行したタスク
  • Meshyウェブアプリ内で行った作業

タスクは完了してはじめて、そのcreated_atの属するウィンドウ内にレコードとして表示されます。Meshyはタスク作成時にクレジットを課金するため、実行中のタスクはレコードにまだ現れません。レコードとクレジット残高を突き合わせる前に、最近のウィンドウを再取得するか、少し時間を置いてからエクスポートしてください。

チームにデータ保持期間が設定されている場合、ウィンドウの開始時刻はその期間が許す範囲より前には遡りません。

Request

GET
/openapi/v1/usage/tasks
curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2",
    "metadata": {}
  }
]

パラメータ

  • Name
    page_num
    Type
    integer
    デフォルト 1
    Description

    返すページ番号で、1から255の範囲です。255を超える値を指定すると400が返されます。1つのウィンドウには最大255ページまで保持されるため、大きなエクスポートはより短いウィンドウに分割してください。

  • Name
    page_size
    Type
    integer
    デフォルト 10
    Description

    1ページあたりのレコード数で、1から100の範囲です。101から255の値を指定すると100件が返され、255を超える値を指定すると400が返されます。

  • Name
    sort_by
    Type
    string
    デフォルト -created_at
    Description

    並び順です。

    利用可能な値:

    • +created_at:古い順
    • -created_at:新しい順

    URL内では、+は%2Bと記述してください。そうしないと+が空白として解釈され、リクエストが400を返します。

  • Name
    start_time
    Type
    string
    Description

    ウィンドウの開始時刻を、RFC 3339形式のタイムスタンプで指定します(例:2026-08-01T00:00:00Z)。この時刻以降に作成されたタスクがレコードに含まれます。省略すると、end_timeの30日前からウィンドウが開始されます。

    ウィンドウは最大366日まで指定できます。これより長いウィンドウを指定すると400が返されるため、長いエクスポートは複数のウィンドウに分割してください。

  • Name
    end_time
    Type
    string
    Description

    ウィンドウの終了時刻を、RFC 3339形式のタイムスタンプで指定します。この時刻より前に作成されたタスクがレコードに含まれます。省略すると、リクエスト時刻がウィンドウの終了時刻になります。

  • Name
    endpoints
    Type
    string
    Description

    含めるエンドポイントをカンマ区切りで指定します。名前はendpointフィールドと同じものを使用します。省略するとすべてのエンドポイントが含まれます。不明な名前を指定すると400が返されます。

    利用可能な値:

    • text-to-3d:すべてのText to 3Dタスク(previewとrefineの両方)
    • text-to-3d-preview:previewタスクのみ
    • text-to-3d-refine:refineタスクのみ
    • image-to-3d
    • multi-image-to-3d
    • retexture
    • remesh
    • convert
    • resize
    • uv-unwrap
    • rig
    • animate
    • text-to-motion
    • text-to-image
    • image-to-image
    • print-multi-color
    • print-repair
    • print-analyze
    • print-split
    • relief
  • Name
    status
    Type
    string
    Description

    含めるステータスで、SUCCEEDEDまたはFAILEDです。省略すると両方が含まれます。それ以外の値を指定すると400が返されます。

返り値

使用状況レコードの配列を返します。一致するレコードがない場合、配列は空になります。

失敗時の挙動

  • Name
    400 - Bad Request
    Description

    いずれかのパラメータが無効です。エラーメッセージにどのパラメータかが示されます。該当のパラメータを修正してから、リクエストを再送してください。

  • Name
    401 - Unauthorized
    Description

    APIキーが指定されていないか、無効です。Authorizationヘッダーを確認してください。

  • Name
    403 - Forbidden
    Description

    APIキーのアカウントが、StudioまたはEnterpriseチームの有効なメンバーではありません。メッセージはThis endpoint is available on Studio and Enterprise plansです。StudioまたはEnterpriseチームのメンバーのAPIキーを使用してください。

  • Name
    429 - Too Many Requests
    Description

    リクエストを送りすぎました。Retry-Afterに示された秒数だけ待ってから、再試行してください。


使用状況レコードオブジェクト

Example usage record object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}
  • Name
    task_id
    Type
    string
    Description

    タスクIDで、作成元のエンドポイントが返したものと同じIDです。出力URLを含むタスク自体を取得するには、このIDをそのエンドポイントの取得用ルートに送信します。例えばimage-to-3dのレコードであればGET /openapi/v1/image-to-3d/{task_id}です。

  • Name
    endpoint
    Type
    string
    Description

    タスクが実行されたエンドポイントで、例えばimage-to-3dやrigです。Text to 3Dタスクの場合は、そのステージであるtext-to-3d-previewまたはtext-to-3d-refineが表示されます。

    古いレコードには、廃止されたエンドポイントの名前が含まれている場合があり、これらはendpointsフィルターでは受け付けられません。

  • Name
    status
    Type
    string
    Description

    タスクの最終ステータスで、SUCCEEDEDまたはFAILEDです。

  • Name
    created_at
    Type
    timestamp
    Description

    タスクが作成された時刻で、Unixミリ秒形式です。

  • Name
    finished_at
    Type
    timestamp
    Description

    タスクが完了した時刻で、Unixミリ秒形式です。タスクに完了時刻がない場合はnullです。

  • Name
    consumed_credits
    Type
    integer
    Description

    タスクが消費したクレジット数で、返金後の値です。タスクが失敗した場合はMeshyが返金するため0になります。また、プリント可能性を分析のような無料タスクも0です。

  • Name
    api_key_name
    Type
    string
    Description

    タスクを実行したAPIキーの名前です。アプリのログインで実行されたタスクの場合は、そのアプリの名前(例:Meshy CLI)になります。

    次のような場合は空文字列になります。

    • プリント可能性を分析のタスクのように、そもそも課金されなかったタスク(無料のため)。
    • APIキーが削除されている場合。
    • APIキーが数分以内に作成されたばかりの場合。
  • Name
    api_key_suffix
    Type
    string
    Description

    そのAPIキーの末尾4文字で、同じ名前のキーを区別するためのものです。api_key_nameが空文字列の場合は常に空文字列になり、Meshy CLIのようなアプリログインの場合も同様です。

  • Name
    metadata
    Type
    object
    Description

    タスク作成時にX-Meshy-Metadataヘッダーで送信されたタグです。何もない場合は{}です。詳細はMetadataを参照してください。