> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 참조

> 기본 URL, 엔드포인트, 응답, 오류, 사용 제한을 정리합니다.

## 개요

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

## 기본 URL과 공통 헤더

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

```text theme={null}
https://api.noimosai.com/noimosToolBridge
```

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

```http theme={null}
Authorization: Bearer nmp_...
Content-Type: application/json
```

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

```http theme={null}
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`에 들어 있습니다.

```json theme={null}
{
  "data": {}
}
```

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

```json theme={null}
{
  "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`에 보냅니다.

```json theme={null}
{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}
```

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

## 관련 페이지

인증과 실행은 다음 페이지에서 설명합니다.

* [요청 인증하기](https://docs.noimosai.com/ko/developers/api/authentication.md)
* [실행과 비용 관리하기](https://docs.noimosai.com/ko/developers/api/execution-and-billing.md)
* [문서](https://platform.noimosai.com/docs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.