前の記事では、CodexのToken消費を入力、推論、出力に分けて見ました。

Codexを使う場合は、ユーザーの依頼だけでなく、AGENTS.md、Skills、MCP、読んだファイル、コマンド結果などもモデルへ渡されます。単純な文章処理だけをアプリケーションへ組み込みたいなら、そこまで大きな仕組みが必要とは限りません。

CodexのTokenは何で決まる？ 入力・推論・出力ごとの節約方法 | kuromica

CodexのToken消費を、モデルへ渡す情報、推論、回答、繰り返し処理に分けて確認します。CLI、AGENTS.md、Skills、MCP、ログ、推論設定など、利用者側で実際に減らせる場所もまとめます。

https://kuromica.com/blog/codex-token-usage-input-reasoning-output/

kuromica · kuromica.com

今回はTypeScriptからResponses APIを直接1回呼びます。

API keyを用意する
↓
OpenAI SDKをinstallする
↓
responses.create()を呼ぶ
↓
output_textを受け取る
↓
usageを見る

AIからアプリケーションの関数を呼び出すFunction Calling、外部サービスとAIをつなぐためのMCP、大量のrequestをまとめて処理するBatch API、長時間の処理をrequestから切り離すBackground Modeなどは、今回は入れません。

2026年9月3日時点の公式JavaScript / TypeScript SDK openai はv7.9.0です。Node.js 22と24 LTSをサポートし、Node.js 22が最低要件です。TypeScriptは4.9以上がサポートされています。

GitHub - openai/openai-node: Official JavaScript / TypeScript library for the OpenAI API

Official JavaScript / TypeScript library for the OpenAI API - openai/openai-node

https://github.com/openai/openai-node

GitHub · github.com

先に完成形を見る

最小コードはこれです。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "TypeScriptのArray.prototype.mapを1文で説明してください",
});

console.log(response.output_text);
console.log(response.usage);

new OpenAI()は環境変数のOPENAI_API_KEYを自動で読みます。responses.create()へモデルと入力を渡し、response.output_textから生成された文章を取り出します。

これだけでもOpenAI APIは使えます。AIに外部の処理を呼ばせ、その結果を見ながら何度も処理を続ける仕組みまで、最初から作る必要はありません。

最小のTypeScript環境を作る

空のディレクトリを作ります。

mkdir openai-api-example
cd openai-api-example
npm init -y
npm install openai
npm install --save-dev tsx typescript @types/node
mkdir src

pnpmなら次のようにできます。

pnpm init
pnpm add openai
pnpm add -D tsx typescript @types/node
mkdir src

この程度のサンプルなら、最初からbuild toolや複雑なtsconfig.jsonを用意する必要はありません。

API keyを設定する

Responses APIを呼ぶには、OpenAI API Platformで発行したAPI keyが必要です。

https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key

help.openai.com

OpenAIのJavaScript / TypeScript SDKは、環境変数OPENAI_API_KEYを標準の認証情報として読み込みます。

export OPENAI_API_KEY="sk-..."

その状態なら、クライアント側ではAPI keyを明示する必要はありません。

import OpenAI from "openai";

const client = new OpenAI();

ローカル開発で.envを使う場合も、同じ名前で設定します。

OPENAI_API_KEY=<your-api-key>

この記事では後ほど--env-file=.envを使って読み込みます。.envはGitへcommitしないようにします。

printf '.env\n' >> .gitignore

必要ならapiKey: process.env.OPENAI_API_KEYと明示しても同じです。API keyをsource codeへ直接書くことも技術的には可能ですが、公開repositoryやlogへ残る事故につながるため、継続利用では環境変数や実行環境のSecret管理機能を使います。

なお、Webhookで使うOPENAI_WEBHOOK_SECRETはAPIを呼ぶためのkeyではなく、OpenAIから届いたWebhookの署名を検証するための別のSecretです。この記事ではWebhookを使わないため設定しません。

また、ChatGPT Plus / Proなどの契約とOpenAI APIのbillingは別です。ChatGPTの有料プランに加入していてもAPI利用料が含まれるわけではありません。

https://help.openai.com/en/articles/9039756-managing-billing-settings-on-chatgpt-web-and-platform

help.openai.com

Responses APIを1回呼ぶ

src/index.tsを作ります。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "TypeScriptのArray.prototype.mapを1文で説明してください",
});

console.log(response.output_text);

実行します。

npx tsx --env-file=.env src/index.ts

pnpmなら次のように実行できます。

pnpm exec tsx --env-file=.env src/index.ts

tsxはNode.jsのCLI flagをそのまま使えるため、Node.jsの--env-fileで.envを読み込めます。

https://tsx.is/node-enhancement

tsx.is

API callが成功すると、response.output_textへモデルの回答が入ります。

Responses APIではoutput配列を自分でたどることもできますが、単純に生成された本文を取り出すだけなら、SDKが提供するoutput_textを使う方が簡単です。

Create a model response

https://developers.openai.com/api/reference/resources/responses/methods/create

OpenAI API Reference · developers.openai.com

なぜgpt-5.6-lunaを使うのか

2026年9月時点のOpenAIのmodel guideでは、GPT-5.6 familyは次のように分けられています。

gpt-5.6-sol
→ 複雑な推論やコーディングを重視した上位モデル

gpt-5.6-terra
→ 性能と料金のバランスを取りやすいモデル

gpt-5.6-luna
→ 料金を抑えたい処理や大量実行を想定したモデル

今回の入力は「1文で説明する」という小さな処理です。モデル比較がこの記事の目的ではないため、単純なtext処理に使いやすいgpt-5.6-lunaを選びます。

Models | OpenAI API

Explore all available models on the OpenAI Platform.

https://developers.openai.com/api/docs/models

OpenAI Developers · developers.openai.com

実際のアプリケーションでは、品質、速度、料金を見ながらmodelを選びます。

inputはまず文字列だけでよい

Responses APIのinputには複数の形式を渡せますが、最初は文字列だけで十分です。

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "この文章を30文字以内で要約してください: ...",
});

Chat形式のmessage配列や画像、fileを最初から理解する必要はありません。

Application
  ↓
input: string
  ↓
Responses API
  ↓
output_text

単純な処理なら、この流れで完結します。

Token使用量を確認する

前の記事とのつながりで、response.usageも確認します。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "TypeScriptのArray.prototype.mapを1文で説明してください",
});

console.log(response.output_text);
console.dir(response.usage, { depth: null });

現在のResponses APIでは、usageに次の情報が含まれます。

usage
├─ input_tokens
├─ input_tokens_details
│  └─ cached_tokens
├─ output_tokens
├─ output_tokens_details
│  └─ reasoning_tokens
└─ total_tokens

個別に見るなら次のように書けます。

console.log("input:", response.usage?.input_tokens);
console.log("cached:", response.usage?.input_tokens_details?.cached_tokens);
console.log("output:", response.usage?.output_tokens);
console.log(
  "reasoning:",
  response.usage?.output_tokens_details?.reasoning_tokens,
);
console.log("total:", response.usage?.total_tokens);

ここでreasoning_tokensはoutput_tokensの内訳です。

input_tokens
+
output_tokens
=
total_tokens

reasoning_tokensをさらに足すわけではありません。

前の記事で扱った「入力Token」「推論Token」「出力Token」は、Responses APIを直接使うとResponse objectから確認できます。

CodexのTokenは何で決まる？ 入力・推論・出力ごとの節約方法 | kuromica

CodexのToken消費を、モデルへ渡す情報、推論、回答、繰り返し処理に分けて確認します。CLI、AGENTS.md、Skills、MCP、ログ、推論設定など、利用者側で実際に減らせる場所もまとめます。

https://kuromica.com/blog/codex-token-usage-input-reasoning-output/

kuromica · kuromica.com

指示と入力を分ける

最小コードではinputだけを使いました。もう一段だけ進めるなら、アプリケーション側の指示とユーザー入力を分けられます。

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions: "回答は日本語で、1文だけ返してください。",
  input: "TypeScriptのArray.prototype.mapを説明してください",
});

console.log(response.output_text);

instructionsには、ユーザーが入力する本文とは別に、アプリケーション側から守らせたい指示を書けます。OpenAI APIでは、このような上位の指示をsystem / developer instructionと呼びます。回答言語や文章量などの共通ルールを、ユーザー入力と分けて管理できます。

推論量や出力を小さくしたい場合

前の記事では、Responses APIまで使うとreasoning.effort、text.verbosity、max_output_tokensを直接指定できると書きました。

TypeScriptでは次のように指定できます。

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  reasoning: {
    effort: "low",
  },
  text: {
    verbosity: "low",
  },
  max_output_tokens: 200,
  input: "TypeScriptのArray.prototype.mapを簡潔に説明してください",
});

console.log(response.output_text);
console.dir(response.usage, { depth: null });

max_output_tokensは、画面に見える回答だけでなくreasoning tokenも含む出力全体の上限です。

小さな分類や短い要約なら、強いreasoningを毎回使う必要はありません。ただし最初から設定を増やすより、まず設定なしで1回動かしてから追加する方がAPIの形を追いやすくなります。

文章分類を1回だけ試す

少し実務寄りの例も試します。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  instructions:
    "frontend / backend / security のどれか1つだけを返してください。",
  input: "Dockerコンテナをrootで動かさないようにする方法",
});

console.log(response.output_text);

これはAPIを1回呼ぶ例としては使えます。

ただし、アプリケーション側で返り値をそのまま処理したい場合は、「frontend / backend / securityのどれか」という形式を文章でお願いするだけでは不十分です。決めたJSON Schemaに沿った形式で返させるStructured Outputsという機能がありますが、この記事ではそこまで実装しません。

最初に詰まりやすいところ

OPENAI_API_KEYが読み込まれていない

.envを作っていても、実行時に--env-file=.envを付け忘れるとSDKはkeyを取得できません。

現在のOpenAI SDKでは、credentialが見つからない場合にMissing credentialsとして失敗します。

API keyが無効

無効なkeyでAPIへ接続するとauthentication errorになります。OpenAI SDKでは4xx / 5xx responseに対してOpenAI.APIError系の例外がthrowされ、401はAuthenticationErrorです。

model名が違う、または利用できない

model名のtypoや利用できないmodelを指定している場合もrequestは失敗します。modelは変更が速いため、時間が経ってからこの記事を読む場合はOpenAIのmodel一覧も確認してください。

Models | OpenAI API

Explore all available models on the OpenAI Platform.

https://developers.openai.com/api/docs/models

OpenAI Developers · developers.openai.com

billing / creditsを確認する

ChatGPT側で有料planを契約していても、API側のbillingとは別です。API Platformのbilling設定やusageも確認します。

429が返る

OpenAI SDKでは429をRateLimitErrorとして扱います。エラー本文とAPI Platformのusage / billingを合わせて確認します。

エラー内容を表示する

少しだけerror handlingを入れるなら次のようにできます。

import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-5.6-luna",
    input: "こんにちは",
  });

  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error("status:", error.status);
    console.error("name:", error.name);
    console.error("request id:", error.requestID);
    throw error;
  }

  throw error;
}

OpenAI公式SDKでも、OpenAI.APIErrorからHTTP statusやrequest IDを確認できます。

GitHub - openai/openai-node: Official JavaScript / TypeScript library for the OpenAI API

Official JavaScript / TypeScript library for the OpenAI API - openai/openai-node

https://github.com/openai/openai-node

GitHub · github.com

外部の処理をAIから呼び出したい場合はFunction Callingを使う

Function Callingは、AIがアプリケーション側の関数やAPIを使うための仕組みです。

例えば「現在の在庫を確認して」とAIへ頼んでも、通常のResponses APIだけではデータベースを直接読めません。そこで、アプリケーション側が「在庫を調べるにはこの関数を使える」とAIへ伝えます。

AI自身がその関数を実行するわけではありません。AIは「この関数を、この引数で呼び出したい」と返し、実際の処理はアプリケーション側が行います。

OpenAIのドキュメントでは、このようにAIから利用できる外部機能をToolと呼ぶことがあります。

利用できる関数と引数をAIへ伝える
↓
AIが呼び出したい関数と引数を返す
↓
アプリケーションが実際に関数を実行する
↓
実行結果をAIへ返す
↓
AIが結果を使って回答する

この流れになるため、Function Callingを使うと「APIを1回呼んで文章を受け取る」よりコードが増えます。

フォーム入力を要約する、文章を分類する、短い説明を作る、といった処理なら、

input
↓
Responses API
↓
output_text

だけで動きます。

データベースを検索する、社内APIを呼ぶ、ファイル操作を依頼するといった外部処理が必要になった段階で、Function Callingを検討すれば十分です。

OpenAI APIでAIが使えるツールを制限する。「使うな」とプロンプトに書くだけで安全なのか？ | kuromica

OpenAI APIでAIに複数のツールを使わせるとき、プロンプトで「使うな」と書くだけで十分なのか。tool_choiceやallowed_tools、Function Callingを使い、AIが使えるツールと実際に実行してよい操作を分けて考えます。

https://kuromica.com/blog/openai-api-tool-control/

kuromica · kuromica.com

Codexとの違いもコードを見ると分かりやすい

Codexはcoding agentとして、repositoryを調べたり、fileを読んだり、commandを実行したりしながら仕事を進めます。

一方、今回のResponses APIにはその仕組みがありません。

Application
  ↓
Responses API
  ↓
Model

必要なinputを送って、結果を受け取るだけです。ここから必要に応じて、決めたJSON形式で返させるStructured Outputs、外部の関数を呼び出すFunction Calling、Web検索などOpenAI側が用意しているbuilt-in tools、長時間処理向けのBackground Mode、大量処理向けのBatch APIを追加できます。

モデルを何度も呼び出し、外部処理の実行結果を受け取って次の判断をさせるようなAgentの実行基盤まで、最初から作る必要はありません。

Codex CLI、Codex SDK、App Server、Responses APIの使い分けは別の記事で扱っています。

Codex CLIでできるならOpenAI APIはいらない？ codex exec・SDK・App ServerとResponses APIを使い分ける | kuromica

Codexをプログラムから呼び出せる現在、Responses APIを直接使うのはどんなときか。codex exec、Codex SDK、App Server、Responses APIを、実装・運用・配布の違いから比較します。

https://kuromica.com/blog/codex-cli-sdk-app-server-responses-api/

kuromica · kuromica.com

この時点でできれば十分なこと

□ API keyをsource codeへ書かない
□ SDKをinstallできる
□ responses.create()を1回呼べる
□ response.output_textを取得できる
□ response.usageを確認できる

ここまで動けば、あとはアプリケーションに必要な機能だけ追加していけます。

大量のrequestをまとめて非同期で処理したい場合はBatch APIがあります。

1万件をAIで処理したい。forループでAPIを呼び続ける設計でいいのか | kuromica

数千・数万件の独立したAI処理をどう実行するか。単純な逐次処理、Queue + Responses API、OpenAI Batch APIを比較し、rate limit、retry、途中失敗、サーバー再起動、料金まで含めて選び方を考えます。

https://kuromica.com/blog/openai-batch-api-large-scale-processing/

kuromica · kuromica.com

数分以上かかる可能性がある処理を、接続中のrequestから切り離して継続させたい場合はBackground Modeを使えます。

AIの処理中にサーバーが落ちたら結果はどうなる？ | kuromica

OpenAI APIで数分かかる処理中にApplicationが再起動したら、結果はどう回収するのか。Background Mode、Webhook、pollingを使い、response IDの永続化、復旧、重複通知、idempotencyまで含めた非同期処理の設計を考えます。

https://kuromica.com/blog/openai-background-mode-webhook-recovery/

kuromica · kuromica.com

AIに本番serverを直接操作させるべきかという設計は別問題です。

AI Agentに本番サーバーのShellを渡す必要はあるのか | kuromica

AI Agentに本番サーバーを操作させるとき、Shellをそのまま渡す必要はあるのか。Shellの自由度と、Function Callingなどで操作を限定する設計を比較し、読み取り・書き込み・承認をどう分けるか考えます。

https://kuromica.com/blog/ai-agent-production-server-shell/

kuromica · kuromica.com

APIを直接使うことと、Agentへ強い権限を渡すことは同じではありません。

まずはresponses.create()を1回呼ぶところから始め、必要になった機能だけ増やします。

動作確認について

この記事のcodeは、2026年9月3日時点のOpenAI公式Responses API reference、model guide、公式JavaScript / TypeScript SDKの現在のAPI surfaceと照合しています。

ただし、この執筆環境ではsecret API keyを扱わないため、実API keyを使った成功requestは実行していません。実行結果やToken数の固定値は記事内へ載せず、response.output_textとresponse.usageを手元で確認する形にしています。

参考資料

OpenAI JavaScript / TypeScript SDK

install方法、runtime要件、Responses API、error handlingについて。

GitHub - openai/openai-node: Official JavaScript / TypeScript library for the OpenAI API

Official JavaScript / TypeScript library for the OpenAI API - openai/openai-node

https://github.com/openai/openai-node

GitHub · github.com

Responses API

input、instructions、max_output_tokens、Response object、usage schemaについて。

Create a model response

https://developers.openai.com/api/reference/resources/responses/methods/create

OpenAI API Reference · developers.openai.com

OpenAI Models

GPT-5.6 Sol / Terra / Lunaの位置づけとmodel IDについて。

Models | OpenAI API

Explore all available models on the OpenAI Platform.

https://developers.openai.com/api/docs/models

OpenAI Developers · developers.openai.com

API key safety

API keyをclient-sideへ置かないこと、repositoryへcommitしないこと、環境変数を使うことについて。

https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety

help.openai.com

ChatGPTとAPIのbilling

ChatGPT subscriptionとAPI Platformのbillingが別であることについて。

https://help.openai.com/en/articles/9039756-managing-billing-settings-on-chatgpt-web-and-platform

help.openai.com

tsx

TypeScriptの実行とNode.js CLI flagの利用について。

https://tsx.is/node-enhancement

tsx.is