使い始める

概要

このページでは、web_searchを例に、APIキーの準備から無料見積もり、実行、結果取得までを試します。特定のプログラミング言語やSDKを使わず、Bash互換シェルとcURLで最初のAPI実行を完了できます。

事前確認

APIを呼び出す前に、次の5点を準備します。

Developer PlatformへログインできるNoimosAIアカウント
API利用が有効なDeveloper Platformのプロジェクト
必要な権限を持つ、nmp_から始まる開発者APIキー
Bash互換シェル
cURL、jq、uuidgen

有料実行まで試す場合は、プロジェクトで利用できる前払いUSD残高と月間上限も確認してください。キーの権限は認証するで説明します。 Developer Platformに利用できるプロジェクトが表示されない場合は、組織のOWNERまたはADMINへプロジェクトの作成か参加権限の追加を依頼してください。APIキーは、参加しているプロジェクト内で作成します。

APIを実行する

最初のAPI実行は、次の7ステップで進めます。

1. Developer PlatformでAPIキーを作成する

プロジェクトのADMINまたはDEVELOPERは、以下の手順でDeveloper PlatformからAPIキーを作成できます。

Developer Platformへログインし、利用するプロジェクトを選択します。
APIキーを開き、新しいキーを作成を選択します。
用途が分かる名前、有効期限、必要な権限を設定して作成します。
一度だけ表示されるシークレットキーを、安全な保管先へ保存します。

このクイックスタートを最後まで試すには、project:read、tools:read、tools:execute、executions:readが必要です。用途が異なる場合は、必要な権限だけを選びます。

2. APIキーと接続先を設定する

秘密情報をコマンド履歴やソースコードへ直接書かないよう、APIキーとBase URLを環境変数へ設定します。

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

APIキーは作成時に一度だけ表示されます。Gitリポジトリ、共有文書、クライアント側のJavaScriptへ保存しないでください。

3. APIキーのプロジェクトを確認する

最初に、キーが想定した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を100万分の1単位の整数で表し、1 USDは1,000,000 microsです。

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

上の金額はレスポンス形式を示す例です。次の手順では、保存したレスポンスから実際の値を取り出します。

6. 見積もった内容を実行する

見積もりと同じツール・引数に、返された料金バージョンと最大予約額を追加します。さらに、1つの論理リクエストを識別する冪等キーを付けます。

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キーと接続先を設定する

3. APIキーのプロジェクトを確認する

4. 利用できるツールを確認する

5. 実行前に見積もりを取得する

6. 見積もった内容を実行する

7. 同じ実行IDで結果を確認する

関連ページ

​概要

​事前確認

​APIを実行する

​1. Developer PlatformでAPIキーを作成する

​2. APIキーと接続先を設定する

​3. APIキーのプロジェクトを確認する

​4. 利用できるツールを確認する

​5. 実行前に見積もりを取得する

​6. 見積もった内容を実行する

​7. 同じ実行IDで結果を確認する

​関連ページ

概要

事前確認

APIを実行する

1. Developer PlatformでAPIキーを作成する

2. APIキーと接続先を設定する

3. APIキーのプロジェクトを確認する

4. 利用できるツールを確認する

5. 実行前に見積もりを取得する

6. 見積もった内容を実行する

7. 同じ実行IDで結果を確認する

関連ページ