> ## 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 키를 설정하고 cURL로 견적, 실행, 결과 조회를 진행합니다.

## 개요

`web_search`를 예로 API 키 준비, 무료 견적, 실행, 결과 조회를 진행합니다. 특정 언어의 SDK 없이 Bash 호환 셸과 cURL로 첫 실행을 완료할 수 있습니다.

## 사전 준비

API 호출 전에 다음 다섯 가지를 준비합니다.

* [Developer Platform](https://platform.noimosai.com)에 로그인할 수 있는 NoimosAI 계정
* API 사용이 활성화된 Developer Platform 프로젝트
* 필수 권한이 있고 `nmp_`로 시작하는 개발자 API 키
* Bash 호환 셸
* cURL, jq, uuidgen

유료 실행을 시도하려면 프로젝트의 선불 USD 잔액과 월간 한도도 확인하세요. 키 권한은 [요청 인증하기](https://docs.noimosai.com/ko/developers/api/authentication.md)에서 설명합니다.

접근 가능한 프로젝트가 없다면 조직의 `OWNER` 또는 `ADMIN`에게 프로젝트 생성이나 참여 권한 추가를 요청하세요. API 키는 참여 중인 프로젝트에서 만듭니다.

## API 실행하기

첫 실행은 다음 일곱 단계로 진행합니다.

### 1. Developer Platform에서 API 키 만들기

프로젝트의 `ADMIN` 또는 `DEVELOPER`는 [Developer Platform](https://platform.noimosai.com)에서 다음과 같이 키를 만듭니다.

1. 로그인하고 사용할 프로젝트를 선택합니다.
2. **API 키**를 열고 **새 키 만들기**를 선택합니다.
3. 용도를 알 수 있는 이름, 만료일, 필수 권한을 지정하고 생성합니다.
4. 한 번만 표시되는 비밀 키를 안전한 곳에 저장합니다.

이 가이드를 완료하려면 `project:read`, `tools:read`, `tools:execute`, `executions:read`가 필요합니다. 다른 용도에서는 필요한 권한만 선택합니다.

### 2. API 키와 기본 URL 설정하기

비밀 정보를 명령 기록이나 소스 코드에 직접 쓰지 않도록 키와 기본 URL을 환경 변수로 설정합니다.

```bash theme={null}
export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."
```

> [!WARNING]
>
> 키는 생성할 때 한 번만 표시됩니다. Git 저장소, 공유 문서, 클라이언트 JavaScript에 저장하지 마세요.

### 3. 키의 프로젝트 확인하기

먼저 키가 의도한 Developer Platform 프로젝트에 연결되는지 확인합니다.

```bash theme={null}
curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"
```

성공하면 `data`에 조직 ID, 프로젝트 ID, 프로젝트 이름이 반환됩니다. 예상한 프로젝트가 아니면 유료 실행 전에 키를 확인하세요.

```json theme={null}
{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}
```

### 4. 사용 가능한 도구 조회하기

현재 도구 이름, 설명, 입력 스키마, 예시, 제공 상태, 요금을 가져옵니다.

```bash theme={null}
NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq
```

전체 응답의 `executionEnabled`와 도구의 `available`을 확인합니다. 도구 수, 모델, 스키마, 요금을 고정값으로 가정하지 말고 이 응답을 현재 기준으로 사용하세요.

`web_search`만 보려면 저장한 응답을 필터링합니다.

```bash theme={null}
echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'
```

### 5. 실행 전 견적 받기

도구 이름과 인수를 보내면 요금 버전과 최대 예약 금액을 받습니다. 유료 처리는 시작되지 않습니다.

```bash theme={null}
NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq
```

견적은 실행에 필요한 `priceVersion`과 `maximumChargeMicros`를 반환합니다. 직접 계산하지 말고 반환된 값을 그대로 사용합니다. `maximumChargeMicros`는 USD의 백만분의 일을 나타내는 정수로, 1 USD는 1,000,000 micros입니다.

```json theme={null}
{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}
```

위 금액은 응답 형식의 예시입니다. 다음 단계에서는 저장한 응답의 실제 값을 읽습니다.

### 6. 견적 받은 내용 실행하기

같은 도구와 인수에 반환된 요금 버전과 최대 예약 금액을 추가하고, 하나의 논리 요청을 식별하는 멱등 키를 지정합니다.

```bash theme={null}
export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')
```

이 예시는 5단계 견적을 재사용하고 `uuidgen`으로 새 멱등 키를 만듭니다. 접수되면 HTTP 202와 실행 ID가 반환됩니다.

```json theme={null}
{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}
```

응답에는 요금 버전, 출력, 오류, 날짜도 포함됩니다. 처리 중 `chargedMicros: 0`은 무료로 정산됐다는 뜻이 아닙니다.

### 7. 같은 실행 ID로 결과 조회하기

6단계에서 저장한 ID로 완료될 때까지 최소 5초 간격으로 조회합니다.

```bash theme={null}
while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done
```

`queued`, `running`, `waiting`은 처리 중입니다. `succeeded`이면 `output`과 `chargedMicros`를 읽습니다. 다른 상태는 [실행과 비용 관리하기](https://docs.noimosai.com/ko/developers/api/execution-and-billing.md)를 참조하세요.

> [!WARNING]
>
> 실행 응답을 모르면 새 멱등 키로 재전송하지 마세요. 같은 본문과 키를 사용하면 이미 접수된 같은 실행을 가져올 수 있습니다.

## 관련 페이지

이후 구현에 필요한 페이지를 참조하세요.

* [요청 인증하기](https://docs.noimosai.com/ko/developers/api/authentication.md): 키 권한과 보관
* [실행과 비용 관리하기](https://docs.noimosai.com/ko/developers/api/execution-and-billing.md): 장시간 처리, 재시도, 정산
* [API 참조](https://docs.noimosai.com/ko/developers/api/reference.md): 엔드포인트, 상태, 제한
* Developer Platform [문서](https://platform.noimosai.com/docs): 최신 예시


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