읽기 전용 API

이용 조건 및 제공 여부

이 가이드는 읽기 전용 API 미리보기를 설명합니다. Studio 계정의 API 키에서 제공 여부를 확인하세요. 결제가 완료된 활성 Studio 또는 Scale 구독이 필요하며, 크레딧 팩만으로는 이용할 수 없습니다.

API 조회는 생성 크레딧을 사용하지 않으며 잔액이 0이어도 가능합니다. 이 버전에서는 사진 업로드, 생성 시작, 파일 다운로드, 프로젝트 변경 또는 결제 관리를 할 수 없습니다. MCP 서버나 ChatGPT 플러그인이 아닌 HTTP API입니다.

키 생성 및 연결

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개 항목과 0~10000의 offset을 지정할 수 있습니다. 다음 요청에는 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
  }
}

제한, 오류 및 재시도

계정당 활성 키는 최대 3개이며 90일 후 만료됩니다. 모든 키가 계정당 분당 60회 요청 제한을 공유합니다. 429 응답을 받으면 Retry-After에 표시된 초만큼 기다린 후 재시도하고, 지속적인 반복 조회는 피하세요.

이용 자격은 요청마다 확인됩니다. 구독이 더 이상 조건을 충족하지 않으면 키가 만료되지 않았어도 API는 403을 반환합니다. Studio에서 키를 취소하는 것은 계속 가능합니다. 취소되거나 만료된 키는 401을 반환하며, 접근 권한이 있으면 새 키를 생성하세요.

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

연동 정보 보호

요청은 서버 또는 신뢰할 수 있는 로컬 스크립트에서 실행하세요. URL, 브라우저 JavaScript, 공개 저장소, 스크린샷 또는 로그에 키를 넣지 마세요. 노출된 키는 즉시 취소하세요. 키는 선택한 프로젝트 하나가 아니라 본인 소유의 모든 프로젝트 메타데이터를 읽을 수 있습니다.

응답에는 원본 사진, 마스크, GLB 파일 내용, 파일 URL 또는 제공업체 인증 정보가 포함되지 않고 메타데이터만 포함됩니다. 창작물을 보고 다운로드하려면 계속 Studio를 이용하세요.