API 참조

개요

Developer Platform API의 공통 연결 정보, 엔드포인트, 응답, 오류, 제한을 정리합니다. 도구별 스키마와 현재 요금은 GET /tools로 가져오세요.

기본 URL과 공통 헤더

모든 경로를 다음 기본 URL에 붙입니다.

https://api.noimosai.com/noimosToolBridge

Developer Platform 키로 인증합니다. JSON 본문에는 Content-Type도 지정합니다.

Authorization: Bearer nmp_...
Content-Type: application/json

유료 실행에는 다음 헤더도 필요합니다.

Idempotency-Key: request-unique-id

엔드포인트

주요 공개 API 엔드포인트는 다음과 같습니다.

메서드와 경로	필수 권한	용도
`GET /tools/project`	`project:read`	키의 조직과 프로젝트 조회
`GET /tools/usage`	`usage:read`	현재 UTC 월의 확정 요청 수와 USD 비용 조회
`GET /tools`	`tools:read`	도구, 스키마, 예시, 제공 상태, 요금 조회
`POST /tools/quote`	`tools:read`	입력에 따른 최대 예약 금액 무료 견적
`POST /tools/upload`	`tools:execute`	명시적으로 보낸 입력을 프로젝트에 비공개 저장
`POST /tools/{tool}`	`tools:execute`	비용 한도 예약 및 유료 작업 등록
`GET /tools/executions`	`executions:read`	프로젝트 실행 목록 조회
`GET /tools/executions/{id}`	`executions:read`	실행 상태, 결과, 확정 비용 조회
`POST /tools/executions/{id}/cancel`	`tools:execute`	취소 요청
`GET /tools/executions/{id}/artifacts/{artifactId}/download`	`executions:read`	생성 파일의 임시 URL 조회

GET /tools/executions는 limit, before, status, tool로 필터링합니다. limit는 1~100이며 기본값은 20입니다.

도구 카탈로그

GET /tools의 data에는 전체 요금 버전, 통화, 실행 가능 여부, 도구 목록이 들어 있습니다. 각 도구에서 다음 정보를 볼 수 있습니다.

name — 실행 URL과 본문에 사용할 도구 이름
description, category — 용도와 분류
available — 필수 외부 서비스가 설정되어 제공 가능한지 여부
inputSchema, example — 입력 JSON Schema와 예시
models — 선택 가능한 모델 및 모델별 예시, 제공 상태, 요금 설명
price — 최소 비용, 과금 단위, 요금 설명

available: true만으로 실행을 보장하지 않습니다. 전체 executionEnabled, 키 권한, 선불 잔액, 월간 한도도 적용됩니다.

응답 형식

성공 응답의 결과는 일반적으로 data에 들어 있습니다.

{
  "data": {}
}

오류는 error에 상태와 메시지가 들어 있습니다.

{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required"
  }
}

모든 응답에 Cache-Control: no-store가 설정됩니다. 키, 결과, 임시 URL을 공유 캐시에 저장하지 마세요.

오류 처리하기

재시도 전에 상태에 따른 원인을 확인합니다.

HTTP	의미	조치
`200`	조회 성공 또는 같은 완료 실행	`data` 처리
`202`	비동기 작업 접수	ID를 저장하고 최소 5초 후 조회
`400`	잘못된 입력, 견적, 상태	카탈로그와 견적 확인
`401`	인증 실패	Authorization, 만료, 폐기 여부 확인
`403`	권한 없음	키 및 프로젝트 권한 확인
`404`	엔드포인트, 작업, 결과물 사용 불가	경로, 제공 상태, 만료 확인
`409`	다른 요청이 멱등 키 사용 중	원래 본문과 키를 확인하고 별도 실행 방지
`429`	요청 한도, 잔액, 월간 한도 도달	해당 한도와 잔액 확인
`503`	실행이나 외부 서비스 일시 불가	재시도 전에 유료 작업 접수 여부 확인

사용 제한

클라이언트에서 다음 제한을 고려하세요.

대상	제한
일반 JSON 요청	UTF-8 기준 64 KiB
업로드 파일	12 MiB
지원 형식	JPEG, PNG, WAV, MP3, MP4
요청 수	API 키마다 고정 1분 구간당 120회
상태 조회 간격	최소 5초
실행당 단계 수	최대 20
생성 파일 보관	30일
다운로드 URL 유효 기간	최대 5분

카탈로그, 견적, 업로드, 실행, 상태 조회, 재전송도 요청 수에 포함됩니다. 429를 피하려면 불필요하게 자주 조회하지 마세요.

입력 파일 업로드하기

로컬 이미지, 오디오, 영상은 MIME 형식과 Base64 데이터를 POST /tools/upload에 보냅니다.

{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}

성공하면 fileId로 사용할 id, 형식, 크기, SHA-256, 만료일을 받습니다. 카탈로그 형식에 맞춰 source 같은 필드에 지정하세요. 같은 프로젝트의 같은 내용은 같은 ID를 반환하며 보관 기한은 최초 업로드부터 연장되지 않습니다.

시작하기

API

CLI

MCP 서버

개요

기본 URL과 공통 헤더

엔드포인트

도구 카탈로그

응답 형식

오류 처리하기

사용 제한

입력 파일 업로드하기

관련 페이지

​개요

​기본 URL과 공통 헤더

​엔드포인트

​도구 카탈로그

​응답 형식

​오류 처리하기

​사용 제한

​입력 파일 업로드하기

​관련 페이지

개요

기본 URL과 공통 헤더

엔드포인트

도구 카탈로그

응답 형식

오류 처리하기

사용 제한

입력 파일 업로드하기

관련 페이지