---
title: "只读 API — 文档 Segmentit"
description: "通过 Segmentit API 预览版，将你的工具连接到项目、资产和任务元数据。"
lang: "zh-Hans"
canonical: "https://segmentit.com/zh-Hans/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}` | 单个项目及其最近任务的标识符（如有）。 |
| 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
  }
}
```

## 限制、错误与重试

每个账户最多可有 3 个有效密钥，密钥在 90 天后过期。所有密钥共享每账户每分钟 60 次请求的限制。收到 429 响应时，请等待 Retry-After 指定的秒数再重试，避免持续轮询。

每次请求都会检查使用资格。订阅不再符合条件时，即使密钥尚未过期，API 也会返回 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、公共仓库、截图或日志。密钥泄露后应立即撤销。一个密钥可读取你所有项目的元数据，而不仅是某个选定项目。

响应仅包含元数据，不包含原始照片、蒙版、GLB 文件内容、文件 URL 或处理服务的凭据。查看和下载作品请继续使用 Studio。