David-Li0406/meta-skill-evloving

OpenAI API - 完全ガイド

バージョン: プロダクション対応 ✅ パッケージ: [email protected] 最終更新日: 2025-11-26

---

ステータス

✅ プロダクション対応:

• ✅ Chat Completions API (GPT-5, GPT-4o, GPT-4 Turbo)
• ✅ Embeddings API (text-embedding-3-small, text-embedding-3-large)
• ✅ Images API (DALL-E 3生成 + GPT-Image-1編集)
• ✅ Audio API (Whisper文字起こし + 11種類の音声のTTS)
• ✅ Moderation API (11の安全カテゴリ)
• ✅ ストリーミングパターン (SSE)
• ✅ ファンクションコーリング / Tools
• ✅ 構造化出力 (JSONスキーマ)
• ✅ ビジョン (GPT-4o)
• ✅ Node.js SDKとfetchアプローチの両方

---

目次

1. クイックスタート
2. Chat Completions API
3. GPT-5シリーズモデル
4. ストリーミングパターン
5. ファンクションコーリング
6. 構造化出力
7. ビジョン (GPT-4o)
8. Embeddings API
9. Images API
10. Audio API
11. Moderation API
12. エラーハンドリング
13. レート制限
14. プロダクションのベストプラクティス
15. openai-responsesとの関係

---

クイックスタート

インストール

npm install [email protected]

環境設定

export OPENAI_API_KEY="sk-..."

または.envファイルを作成:

OPENAI_API_KEY=sk-...

初めてのChat Completion (Node.js SDK)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'ロボット工学の三原則を教えてください。' }
  ],
});

console.log(completion.choices[0].message.content);

初めてのChat Completion (Fetch - Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    messages: [
      { role: 'user', content: 'ロボット工学の三原則を教えてください。' }
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

---

Chat Completions API

エンドポイント: POST /v1/chat/completions

Chat Completions APIは、OpenAIの言語モデルと対話するためのコアインターフェースです。会話型AI、テキスト生成、ファンクションコーリング、構造化出力、ビジョン機能をサポートしています。

サポートされているモデル

GPT-5シリーズ (2025年8月リリース)

• gpt-5: 高度な機能を備えたフル機能の推論モデル
• gpt-5-mini: 優れたパフォーマンスを備えたコスト効率の良い代替モデル
• gpt-5-nano: シンプルなタスク向けの最小/最速バリアント

GPT-4oシリーズ

• gpt-4o: ビジョン機能を備えたマルチモーダルモデル
• gpt-4-turbo: 高速なGPT-4バリアント

GPT-4シリーズ

• gpt-4: オリジナルのGPT-4モデル

基本的なリクエスト構造

{
  model: string,              // 使用するモデル (例: "gpt-5")
  messages: Message[],        // 会話履歴
  reasoning_effort?: string,  // GPT-5のみ: "minimal" | "low" | "medium" | "high"
  verbosity?: string,         // GPT-5のみ: "low" | "medium" | "high"
  temperature?: number,       // GPT-5ではサポートされていません
  max_tokens?: number,        // 生成する最大トークン数
  stream?: boolean,           // ストリーミングを有効にする
  tools?: Tool[],             // ファンクションコーリングツール
}

レスポンス構造

{
  id: string,                 // 一意の完了ID
  object: "chat.completion",
  created: number,            // Unixタイムスタンプ
  model: string,              // 使用されたモデル
  choices: [{
    index: number,
    message: {
      role: "assistant",
      content: string,        // 生成されたテキスト
      tool_calls?: ToolCall[] // ファンクションコーリングの場合
    },
    finish_reason: string     // "stop" | "length" | "tool_calls"
  }],
  usage: {
    prompt_tokens: number,
    completion_tokens: number,
    total_tokens: number
  }
}

メッセージロールと複数ターンの会話

3つのロール: system (動作設定), user (入力), assistant (モデルの応答)。

重要: APIはステートレスです - 毎回のリクエストで完全な会話履歴を送信してください。ステートフルな会話には、openai-responsesスキルを使用してください。

---

GPT-5シリーズモデル

GPT-5モデル（2025年8月リリース）は、推論と冗長性の制御を導入します:

GPT-5.1 (2025年11月13日リリース)

大幅な改善が加えられた最新モデル:

• gpt-5.1: 思考時間を動的に変化させる適応型推論
• 24時間拡張プロンプトキャッシュ: 低コストで高速なフォローアップクエリ
• 新しい開発者ツール: apply_patch（コード編集）、shell（コマンド実行）

破壊的変更: GPT-5.1はデフォルトでreasoning_effort: 'none'になります（GPT-5のデフォルトは'medium'）。移行時にはコードを更新してください！

reasoning_effortパラメータ

思考の深さを制御します（GPT-5およびGPT-5.1で利用可能）:

• "none": 推論なし（最速、最低レイテンシ）- GPT-5.1のデフォルト
• "minimal": 素早い応答、最小限の思考
• "low": 基本的な推論
• "medium": バランスの取れた推論 - GPT-5のデフォルト
• "high": 複雑な問題に対する深い推論

// 推論なしのGPT-5.1（高速）
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: '簡単なクエリ' }],
  // GPT-5.1の暗黙のデフォルトは reasoning_effort: 'none'
});

// 高推論のGPT-5.1（複雑なタスク）
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'この複雑な数学の問題を解いてください...' }],
  reasoning_effort: 'high',
});

verbosityパラメータ

出力の詳細度を制御します（GPT-5/GPT-5.1）:

• "low": 簡潔
• "medium": バランスが取れている（デフォルト）
• "high": 冗長

GPT-5の制限事項

サポートされていません:

• ❌ temperature、top_p、logprobsパラメータ
• ❌ ターン間のステートフルな思考連鎖

代替案: temperature/top_pにはGPT-4oを、ステートフルな推論にはopenai-responsesスキルを使用してください。

---

ストリーミングパターン

stream: true を設定して、トークンごとの配信を有効にします。

Node.js SDK

const stream = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: '詩を書いてください' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

Fetch (Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.1',
    messages: [{ role: 'user', content: '詩を書いてください' }],
    stream: true,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader!.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim() !== '');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') break;

      try {
        const json = JSON.parse(data);
        const content = json.choices[0]?.delta?.content || '';
        console.log(content);
      } catch (e) {
        // 無効なJSONはスキップ
      }
    }
  }
}

Server-Sent Events (SSE) フォーマット:

data: {"id":"chatcmpl-xyz","choices":[{"delta":{"content":"Hello"}}]}
data: [DONE]

重要なポイント: 不完全なチャンク、[DONE]シグナル、無効なJSONを適切に処理してください。

---

ファンクションコーリング

JSONスキーマでツールを定義し、モデルがコンテキストに基づいてそれらを呼び出します。

ツールの定義とリクエスト

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: '場所の現在の天気を取得します',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: '都市名' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location']
    }
  }
}];

const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'サンフランシスコの天気は？' }],
  tools: tools,
});

ツールコールの処理

const message = completion.choices[0].message;

if (message.tool_calls) {
  for (const toolCall of message.tool_calls) {
    const args = JSON.parse(toolCall.function.arguments);
    const result = await executeFunction(toolCall.function.name, args);

    // 結果をモデルに送り返す
    await openai.chat.completions.create({
      model: 'gpt-5.1',
      messages: [
        ...messages,
        message,
        {
          role: 'tool',
          tool_call_id: toolCall.id,
          content: JSON.stringify(result)
        }
      ],
      tools: tools,
    });
  }
}

ループパターン: 応答にtool_callsがなくなるまでAPIを呼び出し続けます。

---

構造化出力

構造化出力を使用すると、モデルの応答にJSONスキーマ検証を適用できます。

JSONスキーマの使用

const completion = await openai.chat.completions.create({
  model: 'gpt-4o', // 注: 構造化出力はGPT-4oで最もよくサポートされています
  messages: [
    { role: 'user', content: '人物のプロフィールを生成してください' }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'person_profile',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'number' },
          skills: {
            type: 'array',
            items: { type: 'string' }
          }
        },
        required: ['name', 'age', 'skills'],
        additionalProperties: false
      }
    }
  }
});

const person = JSON.parse(completion.choices[0].message.content);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }

JSONモード（シンプル）

厳密なスキーマ検証が不要な、よりシンプルなユースケース向け:

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: '3つのプログラミング言語をJSONでリストしてください' }
  ],
  response_format: { type: 'json_object' }
});

const data = JSON.parse(completion.choices[0].message.content);

重要: response_formatを使用する場合は、プロンプトに「JSON」を含めてモデルをガイドしてください。

---

ビジョン (GPT-4o)

GPT-4oはテキストに加えて画像理解をサポートしています。

URL経由の画像

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'この画像には何が写っていますか？' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/image.jpg'
          }
        }
      ]
    }
  ]
});

Base64経由の画像

import fs from 'fs';

const imageBuffer = fs.readFileSync('./image.jpg');
const base64Image = imageBuffer.toString('base64');

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'この画像を詳しく説明してください' },
        {
          type: 'image_url',
          image_url: {
            url: `data:image/jpeg;base64,${base64Image}`
          }
        }
      ]
    }
  ]
});

複数の画像

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'これら2つの画像を比較してください' },
        { type: 'image_url', image_url: { url: 'https://example.com/image1.jpg' } },
        { type: 'image_url', image_url: { url: 'https://example.com/image2.jpg' } }
      ]
    }
  ]
});

---

Embeddings API

エンドポイント: POST /v1/embeddings

テキストをベクトルに変換して、セマンティック検索やRAGに使用します。

モデル

• text-embedding-3-large: 3072次元（カスタム: 256-3072）、最高品質
• text-embedding-3-small: 1536次元（カスタム: 256-1536）、コスト効率が良く推奨

基本的なリクエスト

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: '料理はとても美味しかった。',
});
// 戻り値: { data: [{ embedding: [0.002, -0.009, ...] }] }

カスタム次元数（OpenAI固有）

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'サンプルテキスト',
  dimensions: 256, // デフォルトの1536から削減
});

利点: ストレージを4倍～12倍削減、検索の高速化、品質低下は最小限。

バッチ処理

const embeddings = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['最初の文書', '2番目の文書', '3番目の文書'],
});

制限: 入力あたり8192トークン、バッチ全体で合計300kトークン、最大配列サイズ2048。

重要なポイント: 効率化のためにカスタム次元数を使用し、最大2048文書までバッチ処理し、埋め込みをキャッシュします（決定論的）。

---

Images API

画像生成 (DALL-E 3)

エンドポイント: POST /v1/images/generations

const image = await openai.images.generate({
  model: 'dall-e-3',
  prompt: '印象的な青い目をした白いシャム猫',
  size: '1024x1024', // 他にも: 1024x1536, 1536x1024, 1024x1792, 1792x1024
  quality: 'standard', // または 'hd'
  style: 'vivid', // または 'natural'
});

console.log(image.data[0].url);
console.log(image.data[0].revised_prompt); // DALL-E 3は安全性のためにプロンプトを修正する場合があります

DALL-E 3の詳細:

• サポートするのは n: 1 のみ（リクエストあたり1画像）
• 安全性/品質のためにプロンプトを修正する場合があります (revised_prompt を確認)
• URLは1時間で期限切れになります（永続的な保存には response_format: 'b64_json' を使用）

画像編集（GPT-Image-1）

画像編集APIへのChat Completionsの使用: GPT-Image-1はChat Completions APIを介してアクセスします。

const completion = await openai.chat.completions.create({
  model: 'gpt-image-1',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'image',
          image_url: 'data:image/png;base64,{base64_encoded_image}'
        },
        {
          type: 'text',
          text: 'この画像の背景を削除してください'
        }
      ]
    }
  ],
  // GPT-Image-1固有のパラメータ
  reasoning_effort: 'none' // 編集には推論は不要
});

console.log(completion.choices[0].message.content);

エンドポイント: POST /v1/images/generations (DALL-E 3) モデル: gpt-image-1 (Chat Completions経由)

---

Audio API

音声認識 (Whisper)

エンドポイント: POST /v1/audio/transcriptions

サポートされている形式: flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm 最大ファイルサイズ: 25 MB

import fs from 'fs';

const transcription = await openai.audio.transcriptions.create({
  model: 'whisper-1',
  file: fs.createReadStream('audio.mp3'),
});

console.log(transcription.text);

翻訳: POST /v1/audio/translations - Whisperは英語以外の言語を英語に翻訳できます。

const translation = await openai.audio.translations.create({
  model: 'whisper-1',
  file: fs.createReadStream('german.mp3'),
});

console.log(translation.text); // 英語のテキストを返します

オプション: language, prompt, response_format, temperature, timestamp_granularities

音声合成 (TTS)

エンドポイント: POST /v1/audio/speech

import fs from 'fs';

const speech = await openai.audio.speech.create({
  model: 'tts-1', // または 'tts-1-hd'（高品質）
  voice: 'alloy', // alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse
  input: '本日はご利用いただきありがとうございます！',
  response_format: 'mp3',
});

const buffer = Buffer.from(await speech.arrayBuffer());
fs.writeFileSync('output.mp3', buffer);

利用可能な音声: alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse（11種類） 応答フォーマット: mp3, opus, aac, flac, wav, pcm モデル: tts-1（標準）, tts-1-hd（高品質）

ストリーミングTTS (Node.js SDK):

const speech = await openai.audio.speech.create({
  model: 'tts-1',
  voice: 'alloy',
  input: 'これは長い読み上げテキストです...',
  response_format: 'mp3',
});

// レスポンスストリームを直接パイプ
speech.body?.pipeTo(someWritableStream);

---

Moderation API

エンドポイント: POST /v1/moderations

安全で責任あるAI出力を確保するために、コンテンツをモデレートします。

const moderation = await openai.moderations.create({
  model: 'omni-moderation-latest',
  input: 'レビューするテキストサンプル',
});

console.log(moderation.results[0]);

カテゴリ

カテゴリ	説明
sexual	性的コンテンツ
hate	憎悪表現
harassment	ハラスメント
self-harm	自傷行為
sexual/minors	未成年者に関する性的コンテンツ
hate/threatening	脅迫的な憎悪表現
violence/graphic	グラフィックな暴力
self-harm/intent	自傷行為の意図
self-harm/instructions	自傷行為の指示
harassment/threatening	脅迫的なハラスメント
violence	暴力

返されるもの: 「フラグ付き」（ブール値）、各カテゴリのスコア。

---

エラーハンドリング

一般的なエラーコード

コード	意味	対処法
400	不正なリクエスト	リクエストパラメータを確認してください
401	無効なAPIキー	APIキーが正しく設定されているか確認してください
404	エンドポイントが見つかりません	URLを確認してください
429	レート制限	バックオフしてリトライしてください
500	サーバーエラー	リトライ可能。バックオフしてリトライ

コード例 (Node.js SDK)

try {
  const completion = await openai.chat.completions.create({
    model: 'gpt-5',
    messages: [{ role: 'user', content: 'こんにちは' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error('ステータス:', error.status); // 401, 429, etc.
    console.error('メッセージ:', error.message);
    console.error('コード:', error.code);
  } else {
    // ネットワークエラーなど
    console.error('予期しないエラー:', error);
  }
}

コード例 (Fetch)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ model: 'gpt-5', messages }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`API エラー ${response.status}: ${err.error.message}`);
}

---

レート制限

レート制限の処理

• 429ステータスコードを監視
• 指数バックオフを実装
• リトライ前の待機時間に Retry-After ヘッダーを使用

コード例

async function retryWithBackoff(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof OpenAI.APIError && error.status === 429) {
        const retryAfter = parseInt(error.headers?.['retry-after'] || '1');
        const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
        await new Promise(resolve => setTimeout(resolve, Math.max(retryAfter * 1000, delay)));
        continue;
      }
      throw error;
    }
  }
  throw new Error('最大リトライ回数を超えました');
}

ベストプラクティス

• 組織のレート制限: アカウント/組織レベル。制限は異なります。ダッシュボードまたはレート制限ヘッダーで確認してください。
• 接続プールの再利用: 開いている接続を再利用します。特に高スループットの場合。
• レート制限ヘッダー: x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requestsを監視してください。

---

プロダクションのベストプラクティス

1. スキーマ検証

常に構造化出力（JSONスキーマ）とファンクションコーリングスキーマを使用してください。 型安全で強力なツールです。

2. 適切なモデルを選択

タスク	推奨モデル
複雑な推論、コード	GPT-5 または GPT-5.1 (high reasoning)
一般的なテキスト、会話	GPT-5 または GPT-5.1
高速/低コスト、画像入力	GPT-4o
埋め込み（RAG）	text-embedding-3-small (推奨) または large
画像生成	DALL-E 3
画像編集	GPT-Image-1
文字起こし	Whisper
TTS	tts-1 または tts-1-hd

3. エラー処理

APIエラーには常にtry/catchブロックと指数バックオフを使用してください。

4. プロンプトエンジニアリング

• 明確なシステムプロンプト
• 一貫性を保つために temperature 0 を使用（GPT-4oの場合）
• 正確なフォーマットのために少数ショットの例を示す

5. コスト管理

• 実験にはGPT-5-nanoまたはGPT-4o-miniから始める
• 効率的なためにembedding dimensionsを短くする
• 埋め込み（決定論的）と頻繁なプロンプトをキャッシュする
• 未使用のAPIキーをローテーションする（セキュリティ）

6. セキュリティ

• OPENAI_API_KEYを決して公開リポジトリにコミットしないでください
• 環境変数またはシークレットマネージャーを使用する
• ユーザー入力を検証およびサニタイズする
• モデレーションで悪用をチェックする

7. トークン管理

• 大きなレスポンスには max_tokens を設定する
• usage レスポンスを監視してトークン使用量を追跡する
• コンテキストウィンドウの制限に注意: GPT-5は1Mトークン、GPT-4oは128k

---

openai-responsesとの関係

公式スキル openai-responses は、ステートフルな会話管理のために別のAPI（/v1/responses）を使用します。このスキル（meta-skill-evloving）は /v1/chat/completions のステートレスな使用に焦点を当てています。

openai-responses スキルが適している場合:

• 会話履歴の自動管理が必要な場合
• ステートフルな思考連鎖（推論）が重要な場合
• より高いレベルの会話APIを希望する場合

このスキル（meta-skill-evloving）が適している場合:

• 細かい制御が必要な場合（例: ストリーミングで各チャンクを正確にレンダリング）
• 最小限の依存関係で動作する必要がある場合（Cloudflare Workersのfetchパターン）
• 正確なツール呼び出しとJSONスキーマの定義が必要な場合
• Embeddings / Images / Audio / Moderation APIを扱う場合

両方のスキルをインポートして、特定のタスクに応じて選択できます。