読み取り専用API

利用条件と提供状況

このガイドは読み取り専用APIのプレビュー版を説明します。提供状況はStudioアカウントのAPIキー画面で確認してください。支払い済みの有効なStudioまたはScaleサブスクリプションが必要です。クレジットパックのみでは利用できません。

APIの読み取りでは生成用クレジットを消費せず、残高がゼロでも利用できます。この版では写真のアップロード、生成の開始、ファイルのダウンロード、プロジェクトの変更、請求の管理はできません。HTTP APIであり、MCPサーバーやChatGPTプラグインではありません。

キーを作成して接続する

1. StudioアカウントでAPIキーを開き、連携先が分かる名前を付けて作成します。すべてのキーのスコープはmetadata:readです。
2. シークレットは一度しか表示されません。表示時にコピーし、サーバー側のシークレット管理サービス、またはSEGMENTIT_API_KEYという環境変数に保存します。
3. HTTPSでAuthorization: Bearerヘッダーにキーを指定します。以下の例は設定済みの環境変数を読み取ります。共有するコードにシークレットを直接書き込まないでください。

cURL · Bash

curl --fail-with-body --get \
  'https://segmentit.com/api/v1/projects' \
  --data-urlencode 'limit=20' \
  --header \
  "Authorization: Bearer $SEGMENTIT_API_KEY"

Node.js · サーバーサイドJavaScript

サーバーにSEGMENTIT_API_KEYを設定し、Node.js 22以降でこのサンプルを実行してください。キーはStudio → アカウント → APIで作成できます。

const apiKey = process.env.SEGMENTIT_API_KEY;
if (!apiKey) throw new Error('Set SEGMENTIT_API_KEY');

const response = await fetch(
  'https://segmentit.com/api/v1/projects?limit=20',
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10_000),
  },
);

if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(
    `API error: ${response.status}` +
    (retryAfter ? `; retry after ${retryAfter}s` : ''),
  );
}

const { data: projects, pagination } = await response.json();
console.log(projects);
console.log('Next offset:', pagination.nextOffset);

エンドポイント

ベースURLはhttps://segmentit.com/api/v1です。すべてのリクエストに認証が必要で、キー所有者のデータだけにアクセスできます。識別子にはAPIが返すUUIDを使います。JSONフィールド名とステータス値は、どの言語でも英語のままです。

処理のレスポンスには最後に保存された状態（queued、running、succeeded、failed、cancelled）が含まれます。読み取りでは処理プロバイダーへの更新確認や処理の開始は行いません。最新の処理状態が必要な場合は、Studioでプロジェクトを更新してください。

OpenAPIスキーマ · JSON

ページネーションとレスポンス

一覧はdataとpaginationを返します。limitの既定値は20で、1〜50件を指定できます。offsetは0〜10000です。次のリクエストにはnextOffsetを使い、nullになったら終了します。単一のプロジェクトまたは処理はdataオブジェクトのみを返します。日時はISO 8601形式です。

{
  "data": [
    {
      "id": "7b5e26c3-e260-409a-bbb9-b5719f9dbfb0",
      "name": "Launch",
      "kind": "personal",
      "latestJobId": null,
      "createdAt": "2026-10-09T10:00:00.000Z",
      "updatedAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "nextOffset": null
  }
}

制限・エラー・再試行

1アカウントにつき有効なキーは3つまでで、90日後に期限切れとなります。すべてのキーで、1アカウントあたり毎分60リクエストの制限を共有します。429レスポンスではRetry-Afterに記載された秒数を待ってから再試行し、連続したポーリングは避けてください。

利用資格はリクエストごとに確認されます。サブスクリプションが条件を満たさなくなると、キーが有効期限内でも403を返します。Studioでのキーの失効は引き続き可能です。失効済みまたは期限切れのキーは401を返します。利用可能な場合は新しいキーを作成してください。

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required."
  }
}

連携の機密情報を守る

リクエストはサーバー、または信頼できるローカルスクリプトで実行してください。URL、ブラウザーのJavaScript、公開リポジトリ、スクリーンショット、ログにキーを含めないでください。漏えいしたキーは直ちに失効させてください。キーは選択した1件だけでなく、自分のすべてのプロジェクトのメタデータを読み取れます。

レスポンスにはメタデータのみが含まれます。元の写真、マスク、GLB本体、ファイルURL、プロバイダーの認証情報は返しません。作品の表示とダウンロードには引き続きStudioを使ってください。