---
title: "読み取り専用API — ドキュメント Segmentit"
description: "Segmentit APIのプレビュー版で、プロジェクト・アセット・処理のメタデータを自分のツールから確認できます。"
lang: "ja"
canonical: "https://segmentit.com/ja/docs/api/"
---

# 読み取り専用API

Segmentit 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

```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で作成できます。

```javascript
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でプロジェクトを更新してください。

| エンドポイント | レスポンス |
| --- | --- |
| GET`/projects` | 自分のプロジェクト一覧。ページネーション対応。 |
| GET`/projects/{id}` | 1件のプロジェクトと、存在する場合は最新の処理ID。 |
| GET`/projects/{id}/assets` | 生成済みGLBアセットのメタデータ。ページネーション対応。ファイルのダウンロードは不可。 |
| GET`/jobs/{id}` | セグメンテーションまたは再構成処理の保存済み状態。 |

[OpenAPIスキーマ](https://segmentit.com/openapi.json)

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

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

```json
{
  "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を返します。利用可能な場合は新しいキーを作成してください。

| HTTP | エラーコード | 対処方法 |
| --- | --- | --- |
| 400 | `invalid_request / invalid_id` | UUIDまたはページネーションのパラメーターを確認してください。 |
| 401 | `invalid_api_key` | Bearerキーを確認してください。未指定、期限切れ、または失効済みの可能性があります。 |
| 403 | `subscription_required` | 対象の支払い済み有効サブスクリプションが必要です。 |
| 404 | `not_found` | リソースが存在しないか、このアカウントではアクセスできません。 |
| 405 | `method_not_allowed` | 記載のエンドポイントにはGETを使ってください。 |
| 429 | `rate_limited` | Retry-Afterの時間を待ってから再試行してください。 |
| 503 | `api_unavailable` | APIプレビュー版が無効、または一時的に利用できません。Studioで利用状況を確認してください。 |

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

## 連携の機密情報を守る

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

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