시작하기

개요

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

사전 준비

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

Developer Platform에 로그인할 수 있는 NoimosAI 계정
API 사용이 활성화된 Developer Platform 프로젝트
필수 권한이 있고 nmp_로 시작하는 개발자 API 키
Bash 호환 셸
cURL, jq, uuidgen

유료 실행을 시도하려면 프로젝트의 선불 USD 잔액과 월간 한도도 확인하세요. 키 권한은 요청 인증하기에서 설명합니다. 접근 가능한 프로젝트가 없다면 조직의 OWNER 또는 ADMIN에게 프로젝트 생성이나 참여 권한 추가를 요청하세요. API 키는 참여 중인 프로젝트에서 만듭니다.

API 실행하기

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

1. Developer Platform에서 API 키 만들기

프로젝트의 ADMIN 또는 DEVELOPER는 Developer Platform에서 다음과 같이 키를 만듭니다.

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

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

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

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

export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."

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

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

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

curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"

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

{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}

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

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

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만 보려면 저장한 응답을 필터링합니다.

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

5. 실행 전 견적 받기

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

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입니다.

{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}

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

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

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

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가 반환됩니다.

{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}

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

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

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

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를 읽습니다. 다른 상태는 실행과 비용 관리하기를 참조하세요.

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

API

CLI

MCP 서버

시작하기

개요

사전 준비

API 실행하기

1. Developer Platform에서 API 키 만들기

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

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

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

5. 실행 전 견적 받기

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

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

관련 페이지

​개요

​사전 준비

​API 실행하기

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

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

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

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

​5. 실행 전 견적 받기

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

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

​관련 페이지

개요

사전 준비

API 실행하기

1. Developer Platform에서 API 키 만들기

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

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

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

5. 실행 전 견적 받기

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

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

관련 페이지