生成AI APIの使い方｜認証・入出力・再試行まで実装する

生成AI APIの導入は、リクエストを一度成功させただけでは完了しません。秘密鍵を外へ出さず、入力と出力を追跡し、失敗の種類ごとに再試行可否を決め、費用と遅延を測れるところまでを接続基盤として設計します。本稿の成果物は、Node.jsで動く最小APIと、その本番移行可否を判定する「接続受入票」です。

生成AI API実装前のデータ条件と責任範囲を決める

最初に、入力データの所有者、許容用途、保存期間、回答を採用する責任者を一枚へ記録します。試作では公開情報か匿名化した架空データを使い、本番の顧客情報や未公開契約をそのまま送らないでください。入力例30件は、通常12件、長文6件、空欄・上限超過など境界6件、禁止情報や指示衝突を含む異常6件に分けます。期待する回答形式と「回答してはいけない状態」を各行へ付け、実装者が都合のよい質問だけを選べないように固定します。

実行環境はサポート期間中のLTSを選びます。Node.jsの公式リリース表では各系列の状態と終了予定が更新されているため、2026年7月30日に参照したNode 24系LTSを本稿の確認環境とし、導入時には組織の保守期間に合う系列を再確認します^[5]。バージョンは「node」「OpenAI SDK」「アプリ」「プロンプト」の4点をロックファイルと実行ログへ残します。モデル名だけを記録しても、SDK更新や前処理差分があれば同じ応答条件を再現できません。

業務責任者は送信可否と回答の利用条件を承認し、開発者は認証・検証・ログ・再試行を実装し、運用担当は鍵の交換と障害監視を担います。法務・セキュリティ判断が未了なら、開発用の架空データで接続確認までに留めます。データ所有者が決まらない案件は「まず動かす」を理由に本番情報へ広げず、所有権の確定を着手条件として保留します。

APIキーをブラウザへ露出しない接続構成にする

生成AI事業者への通信は、自社のサーバーから行います。ブラウザやスマートフォンアプリへ長期APIキーを埋め込むと、画面配布物や通信解析から第三者が取得し、組織の費用枠で利用できる状態になります。OpenAIの公式クイックスタートも、APIキーを環境変数へ保存し、SDKが実行環境から読み取る手順を示しています^[1]。リポジトリ、HTML、クライアント側JavaScript、問い合わせログには秘密値を残しません。

利用者のブラウザ
  │  自社認証済みのHTTPS
  ▼
自社API ── 入力検証 ── 利用上限 ── 監査ログ
  │                         │
  │ サーバー側の短期認証    └─ request_idだけを画面へ返す
  ▼
生成AI API

自社APIでは、利用者IDから直接APIキーを選ばず、用途別のサービスIDと権限を割り当てます。開発・検証・本番の鍵を分離し、秘密管理サービスから実行時に取得し、表示や例外メッセージでは末尾4文字さえ出さない方針にします。OWASP ASVS 5.0.0はWebアプリケーションの技術的セキュリティ統制を検証する基準として公開されており、認証、アクセス制御、暗号、ログなどを接続機能の受入観点へ組み込めます^[8]。

鍵の漏えいを検知した場合は通信成否を確認する前に失効させます。漏れた鍵を残したままコードだけ直すと、第三者利用が継続する可能性があります。失効時刻、交換対象、影響期間の利用量、該当request_idを記録し、新しい鍵は別の秘密IDとして配布します。交換後に旧鍵で401となること、新鍵で最小リクエストだけ成功することを確認してから通常試験へ戻します。

Responses APIへ最小リクエストを送る

OpenAIは新規統合にResponses APIを推奨し、Chat Completionsからの移行ガイドで入力・出力の対応を説明しています^[2]。以下は、受け取った質問をサーバー側で長さ確認し、用途を固定した指示とともに送る最小例です。モデルは環境変数で固定し、デプロイごとに勝手に最新名へ変えません。出力は`output_text`を取り出しますが、空文字や想定上限超過を正常回答として扱わない追加検証が必要です。

import OpenAI from "openai";
const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL ?? "gpt-5.6";
export async function draftAnswer(question, requestId) {
  const normalized = String(question ?? "").trim();
  if (normalized.length < 1 || normalized.length > 4000) {
    return { ok: false, code: "INPUT_LENGTH", requestId };
  }
  const response = await client.responses.create({
    model: MODEL,
    instructions:
      "社内FAQの下書きを日本語で作る。根拠がない事項は断定しない。",
    input: normalized,
    max_output_tokens: 800
  });
  const text = response.output_text?.trim() ?? "";
  if (text.length === 0) {
    return { ok: false, code: "EMPTY_OUTPUT", requestId };
  }
  return {
    ok: true,
    requestId,
    providerRequestId: response.id,
    model: MODEL,
    text
  };
}

確認順序は、依存関係の導入、環境変数の設定、開発用鍵で一件実行、応答IDの保存、鍵を外した状態で401になることの確認です。最初から30件を並列送信すると、認証ミスとレート上限を同時に起こして原因を読みづらくします。一件成功した後も、入力本文や出力全文を開発コンソールへ無条件表示せず、個人情報を除いた件数、文字数、状態、処理時間で動作を確かめます。

この例は回答生成だけを行い、メール送信やデータ更新をしません。生成結果を別システムへ登録する場合は、API応答の成功と業務更新の成功を同じ処理とみなさず、登録前の承認、重複防止キー、更新失敗時の復旧を別に設計します。外部作用まで一つの関数へ詰め込むと、生成APIの再試行が二重登録を引き起こすためです。

生成AI APIの入出力契約と記録項目を固定する

自社APIの契約は、生成AI事業者の生レスポンスをそのまま画面へ渡さず、業務に必要な項目へ狭めます。入力は`question`、`purpose`、`request_id`、利用者の認可情報、出力は`status`、`answer`、`reason_code`、追跡IDとします。質問が空、用途が未許可、文字数が上限外なら事業者へ送る前に拒否します。回答側も空、禁止形式、機密らしき値、業務上必要な注意書きの欠落を検査し、検査不合格をHTTP通信成功と区別します。

エラー表現にはRFC 9457のProblem Detailsを利用すると、自社APIの問題種別、状態、詳細、インスタンスを機械可読にできます^[7]。ただし、事業者から返った内部メッセージや秘密情報を`detail`へ転記しません。利用者には修正可能な情報だけを示し、運用ログには分類コードとプロバイダーのrequest IDを保存します。画面用メッセージと調査証拠を分けることで、親切なエラー表示が情報漏えいになるのを避けられます。

ログ本文は最小化し、必要なら入力と出力を別の暗号化領域へ期限付きで保存します。通常監視には分類、長さ、ハッシュ、状態だけを使い、内容閲覧はインシデント番号と承認者を必要とする運用にします。テストデータの期待値も版管理し、プロンプト変更と同時に期待値を書き換えないでください。実装に合わせて正解を動かすと、回帰を発見できなくなります。

重複実行の確認では、同一のrequest_idを二度送る試験を、正常応答、一回目の応答が途中で切れた場合、後続保存だけが失敗した場合に分けます。確認例として各ケースを10回ずつ実行し、生成要求と業務更新が一件だけ残るかを追跡レコードで照合します。一回目の状態が不明なときは新規生成へ進まず、まず状態照会を行います。状態照会ができないAPIでは、自社側の冪等記録を確定するまで再送を保留する設計が必要です。これにより、通信エラーを直す操作が二重課金や二重登録を生まないかを公開前に確認できます。

生成AI APIの障害を入力・認証・上限・事業者へ切り分ける

APIが失敗したら、同じ送信を連打する前に状態を分類します。OpenAIの公式エラーガイドは、401を認証、403をアクセス、429をレートまたは利用上限、5xxをサーバー側などに分け、原因に応じた対処を示しています^[3]。自社側では、通信前の入力拒否、DNS・接続タイムアウト、HTTP状態、応答解析、出力検査、後続保存の六段階へ分け、最初に失敗した段階だけを主原因にします。

切り分けでは、失敗したrequest_idと同時刻の正常一件を対照にします。全利用者で401なら共通鍵、特定用途だけ403なら権限、長文だけ429ならトークン量、特定release_idだけ解析失敗ならアプリ変更を疑えます。時刻、リージョン、モデル、入力長、試行番号をそろえず「たまに落ちる」とまとめると、異なる原因を一つの改善へ押し込みます。

顧客データの混入、鍵の露出、他利用者の応答表示を見つけた場合は通常の不具合票へ流さず、直ちにセキュリティ事故経路へ移します。調査用に応答本文をチャットへ貼る行為も止め、アクセス制限された証拠保全領域で扱います。品質が悪いだけの事象と機密性が破られた事象では、許容できる調査速度と再開権限が異なります。

失敗を増幅しない上限付き再試行を実装する

429や一時的な5xxには、指数バックオフへランダムな揺らぎを加え、最大回数を決めます。OpenAIのレート制限ガイドはランダム化した指数バックオフを案内し、失敗した要求も分単位の上限へ数えられるため、即時連打は解決にならないと説明しています^[4]。本稿の初期値は最大3回、基準500ミリ秒、上限8秒、全体期限20秒です。SLAとジョブ特性に合わせて試験し、待ち時間を無制限に伸ばしません。

待機時間（ms） = min（8,000, 500 × 2^試行番号） + 0〜250の乱数

総試行数 = 初回1回 + 再試行回数。ただし処理期限20秒を超える前に打ち切る

const RETRYABLE = new Set([429, 500, 502, 503, 504]);
async function withRetry(send, deadlineMs = 20_000) {
  const startedAt = Date.now();
  let lastError;
  for (let attempt = 0; attempt <= 3; attempt += 1) {
    try {
      return await send({ attempt });
    } catch (error) {
      lastError = error;
      const status = Number(error?.status ?? 0);
      const delay = Math.min(8000, 500 * 2 ** attempt)
        + Math.floor(Math.random() * 251);
      const outOfTime = Date.now() - startedAt + delay > deadlineMs;
      if (!RETRYABLE.has(status) || attempt === 3 || outOfTime) {
        throw error;
      }
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw lastError;
}

RFC 9110では、同一の要求を再送しても業務上の効果が一度だけ生じるメソッドを冪等として説明し、通信失敗後の自動再試行判断と結び付けています^[6]。回答生成そのものが外部更新を伴わなくても、後段で発注や送信をするなら一つのキーで一回だけ確定させます。タイムアウト時に事業者処理が完了したか不明な状態を「失敗」と断定せず、応答IDや自社の確定記録を照会してから次の操作を決めます。

再試行対象外は、入力不備、認証・認可失敗、利用規約上の拒否、出力検査の恒常的不合格です。これらを回数だけ変えても条件は改善しません。一時障害でも、同一モデルの5xx率が5分窓で20%を超える、全体期限を越える、利用量が日次上限の90%へ達する、といういずれかでキュー投入を止めます。待機中の件数を監視せず再試行を追加すると、復旧時に集中送信して再び上限へ達します。

生成AI APIの費用・成功率・遅延を同じ母数で計算する

料金単価はモデルや契約で変わるため、記事へ固定額を書かず、実行日と料金表版を設定へ保存します。一件費用は入力利用量と出力利用量へ各単価を掛け、追加機能の課金があれば加えます。通信成功率だけでは、空出力や検査拒否を成功へ含めてしまいます。そこでHTTP成功、検査通過、業務採用を段階別に集計し、「どこまで使える回答になったか」を分母付きで示します。

一件推定費用 = 入力単位 × 入力単価 + 出力単位 × 出力単価 + 追加機能費

受入成功率 = 出力検査を通過した件数 ÷ 実行対象件数 × 100

採用一件当たり費用 = 全試行費用 ÷ 業務担当が採用した回答件数

再試行率 = 2回以上送信したcase数 ÷ 実行case数 × 100

たとえば30件のうちHTTP成功が29件、形式検査通過が27件、業務採用が21件なら、接続成功率96.7%、受入成功率90.0%、採用率70.0%です。一回目に失敗して二回目で成功した5件も総費用と遅延へ含めます。成功した最終試行だけを集計すると、障害時に費用が増えた事実が見えません。費用は平均と最大、遅延は中央値とp95を併記し、少数の重い入力を確認します。

閾値は上の例をそのまま全社基準にせず、試験集合のベースラインと業務SLAから決めます。重大な情報漏えいは平均値へ入れて薄めず一件で停止、品質や遅延は連続窓で警戒というように、性質の異なる指標を分けます。価格改定やモデル変更があった日は前後を別系列にし、改善率を計算するときに単価差と利用量差を混同しません。

記事固有の接続受入票で修正後を再試験する

受入試験では、最初に固定した30件を同じrelease_idで実行し、正常系だけでなく境界系と異常系を合格させます。修正は一回につき認証、入力制限、再試行、プロンプトなど一要素に絞ります。OpenAIの変更と自社修正が同時に入った場合は、その回を比較用ベースラインにせず、新しい版として再取得します。実行順による偏りを減らすためcase順を固定または記録し、並列数も前後で一致させます。

不合格を修正したら、該当ケースだけでなく三群を再実行します。第一群は失敗ケース、第二群は同じ境界を持つ近傍ケース、第三群は以前から正常だった対照ケースです。失敗6件のうち5件が直れば修正成功率83.3%ですが、対照12件中2件が悪化すれば回帰率16.7%です。前者だけを見て完了にせず、重大失敗0、回帰0、受入成功率の基準達成、p95と費用の許容内を同時に満たします。

受入可否は、開発者が「レスポンスを取得できた」と宣言した時点ではなく、業務責任者が試験票の入力・出力条件を確認し、運用担当が監視と鍵交換を実行できる時点で決めます。

再試験の結果には、未実行件数も必ず残します。外部障害で6件を試せなかった場合、24件合格を「30件合格」と扱いません。未実行理由、再開予定、影響する合否項目を記載し、母数がそろうまで条件付き合格に留めます。試験証拠から秘密値と本文を除いたうえで、release_idから追跡できる場所へ保存します。

API接続を停止する条件と採用に向かないケースを定める

即時停止は、APIキー露出、未許可データの外部送信、他利用者の応答混入、認可回避、予算上限超過です。新規送信を遮断し、影響する鍵を失効させ、キューを凍結し、証拠を保全します。401・403が連続する場合も鍵を自動で差し替えず、設定者が環境と権限を確認します。5xxや429は、5分窓の失敗率20%超、待機中100件超、日次利用枠90%到達のいずれかでサーキットを開きます。

このAPI接続方式が向かないケース

• ブラウザだけで完結し、秘密情報を保持できる自社サーバーがない。
• 入力データの所有者や外部送信可否を決める担当がいない。
• 回答の誤りを人が確認できず、そのまま医療・法務・与信などの確定判断に使う。
• ログ保存が一切許されず、request_idさえ残せないため障害再現ができない。
• 一件の遅延や外部停止も許容できず、代替処理や手動経路を用意できない。

向かない条件がある場合は、サーバー経由の構成を先に用意する、送信対象を公開情報へ限定する、生成結果を参考情報へ落とす、オンプレミス等の別方式を比較する、という順で再検討します。単に「AIを使わない」で終えるのではなく、どの制約が接続方式と衝突したかを記録すれば、条件が変わった際に再評価できます。

専門担当への引継ぎ票には、発生時刻、request_id、release_id、SDKとモデル、入力分類、HTTP状態、試行履歴、利用量、影響利用者、暫定遮断、再現手順を記載します。本文や秘密値は必要最小限の別領域へ置きます。再開には、原因修正、漏えいした鍵の失効、失敗・近傍・対照の再試験、監視アラート確認、データ所有者と運用責任者の承認が必要です。

生成AI APIの実装を始める次の行動

最初の一日は、公開または架空データの30件を作り、用途、期待形式、送信禁止条件を付ける作業へ使います。次にNode.jsとSDKの版を固定し、開発用の秘密IDを環境変数から読み、通常一件だけをResponses APIへ送ります。応答本文を広く保存する前に、自社request_id、事業者応答ID、状態、入力・出力利用量、処理時間を結べることを確かめます。

二日目は、空欄、上限超過、401、403、429、503、空出力、保存失敗を意図的に発生させます。各状態が入力拒否、停止、上限付き再試行、出力隔離、後続処理の再開へ正しく分かれるかを受入票へ記入します。再試行は最大3回と20秒期限を実測し、失敗要求を増幅しないことを送信時刻から確認します。

三日目は固定30件を実行し、受入成功率、採用率、再試行率、p95遅延、採用一件当たり費用を算出します。失敗を直した後は失敗群・近傍群・対照群を同じ並列数で再試験します。秘密露出0件、未許可送信0件、重大失敗0件、回帰0件を満たし、運用担当が鍵交換とサーキット停止を実演できた状態を本番検討へ進む条件とします。

この段階で関数実行が必要になった場合は、接続基盤へ直接コードを継ぎ足さず、052の引数検証と権限境界を設計します。複数の外部処理を連ねる要件なら、さらに053の状態機械と補償処理へ分けます。役割を分けることで、回答生成の再試行が業務更新を重複させる事故を防ぎ、API接続の障害原因も単独で追跡できます。

参考文献・出典

1. OpenAI公式ドキュメント「Developer quickstart」（継続更新ページ、版表記なし。参照日: 2026年7月30日）
2. OpenAI公式ドキュメント「Migrate to the Responses API」（継続更新ページ、版表記なし。参照日: 2026年7月30日）
3. OpenAI公式ドキュメント「Error codes」（継続更新ページ、版表記なし。参照日: 2026年7月30日）
4. OpenAI公式ドキュメント「Rate limits」（継続更新ページ、版表記なし。参照日: 2026年7月30日）
5. OpenJS Foundation公式「Node.js Releases」（リリース表は継続更新。Node 24系の状態を2026年7月30日に参照）
6. IETF公式仕様「RFC 9110: HTTP Semantics」（RFC 9110、公開: 2022年6月、参照日: 2026年7月30日）
7. IETF公式仕様「RFC 9457: Problem Details for HTTP APIs」（RFC 9457、公開: 2023年11月、参照日: 2026年7月30日）
8. OWASP公式「Application Security Verification Standard」（ASVS 5.0.0、公開: 2025年5月30日、参照日: 2026年7月30日）