PHPからGroq APIを呼び出す方法|cURLのコード例と403・429の対処
作成日:2026.11.22
PHPのcURL拡張を使って、GroqCloudのChat Completions APIから生成テキストを取得する方法を紹介します。APIキーとモデルIDを環境変数で設定し、通信エラーとHTTPエラーを切り分けるところまでコード例で解説します。403が返ったときのモデル利用権限の確認、429が返ったときのレート制限の確認、JSON形式の応答を扱う際の注意点もまとめます。
GroqCloudは、大規模言語モデル(LLM)を高速に実行できる推論APIサービスです。実際にPowerShellから短い文章を生成してみたところ、特にモデルの推論量を抑えたときはレスポンスが返ってくるのがかなり速く、印象に残りました。
今回は、PHPからGroqのChat Completions APIへテキストを送り、応答を取り出してみます。APIキーとモデルIDを環境変数から読み込み、通信エラーとHTTPエラーを分けて確認するところまで実装します。
Groqと、xAIのGrokは別のサービスです。この記事ではGroqCloudのAPIを扱います。APIのエンドポイントや利用できるモデルは変更されることがあるため、モデルIDなどはGroqの対応モデル一覧で確認してください。
PHPからAPIを呼び出す準備
この記事の例では、PHPのcURL拡張を使います。まず、実行するPHPで拡張が有効か確認します。
php -m
出力にcurlがあれば利用できます。ブラウザーから動かすPHPとコマンドラインのPHPが別の場合は、この記事のスクリプトを実行するPHPで確認してください。
GroqCloudでAPIキーを発行したら、ソースコードへ直接書かずに環境変数へ設定します。PowerShell 7でスクリプトを試す場合は、次のようにします。APIキーは入力時に画面へ表示されません。
$env:GROQ_API_KEY = Read-Host "Groq API Key" -MaskInput
$env:GROQ_MODEL_ID = "openai/gpt-oss-120b"
ここで設定した値は、このPowerShellと、そこから起動するPHPプロセスで使えます。Apacheなどから実行する場合は、Webサーバー側のプロセスにも環境変数を設定してください。getenv()は環境変数を読み込みますが、PHPが.envファイルを自動で解析するわけではありません。Laravelなどでは、フレームワークが読み込んだ値を参照する方法に合わせます。
この記事では、2026年11月22日時点で利用可能なモデルの一例としてopenai/gpt-oss-120bを指定しています。モデルの提供状況やアカウントごとの利用権限は変わるため、同じIDを使えない場合は対応モデル一覧とGroqCloudの設定を確認してください。
PHPからChat Completions APIを呼び出す
GroqのChat Completions APIへは、次のエンドポイントにPOSTリクエストを送ります。
https://api.groq.com/openai/v1/chat/completions
リクエストには、利用するモデルとメッセージをJSONで指定します。次の例は、コマンドラインから実行するPHPスクリプトです。groq-chat.phpとして保存します。
<?php
declare(strict_types=1);
$apiKey = getenv('GROQ_API_KEY');
$modelId = getenv('GROQ_MODEL_ID');
if ($apiKey === false || $apiKey === '') {
throw new RuntimeException('環境変数 GROQ_API_KEY が設定されていません。');
}
if ($modelId === false || $modelId === '') {
throw new RuntimeException('環境変数 GROQ_MODEL_ID が設定されていません。');
}
$requestBody = json_encode([
'model' => $modelId,
'messages' => [
[
'role' => 'user',
'content' => 'PHPからGroq APIを呼び出すときの注意点を3つ挙げてください。',
],
],
'max_completion_tokens' => 1024,
], JSON_THROW_ON_ERROR);
$curl = curl_init('https://api.groq.com/openai/v1/chat/completions');
if ($curl === false) {
throw new RuntimeException('cURLを初期化できませんでした。');
}
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $requestBody,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 120,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
],
]);
$responseBody = curl_exec($curl);
if ($responseBody === false) {
$curlError = curl_error($curl);
curl_close($curl);
throw new RuntimeException('Groq APIとの通信に失敗しました: ' . $curlError);
}
$httpStatus = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpStatus < 200 || $httpStatus >= 300) {
$errorData = json_decode($responseBody, true);
$errorMessage = is_array($errorData)
? ($errorData['error']['message'] ?? null)
: null;
if (!is_string($errorMessage) || $errorMessage === '') {
$errorMessage = 'レスポンス本文を確認してください。';
}
throw new RuntimeException(sprintf(
'Groq APIがHTTP %dを返しました: %s',
$httpStatus,
$errorMessage
));
}
$responseData = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);
$choice = $responseData['choices'][0] ?? null;
$content = $choice['message']['content'] ?? null;
$finishReason = $choice['finish_reason'] ?? null;
if (!is_string($content)) {
throw new RuntimeException('応答にテキストがありません。finish_reasonを確認してください。');
}
if ($finishReason === 'length') {
throw new RuntimeException('生成がトークン上限で終了しました。出力上限を見直してください。');
}
echo $content, PHP_EOL;
リクエスト本文はjson_encode()でJSONにし、認証にはAuthorization: Bearerヘッダーを使います。CURLOPT_RETURNTRANSFERを有効にすると、curl_exec()のレスポンスを変数で受け取れます。
先ほどのPowerShellからスクリプトを実行します。
php .\groq-chat.php
成功すると、モデルが生成したテキストが表示されます。Chat Completions APIの応答にはchoices配列があり、各選択肢のmessage.contentにテキスト、finish_reasonに生成の終了理由が含まれます。ここでは最初の選択肢を取り出しています。
通信エラーとHTTPエラーを分けて確認する
API呼び出しに失敗したら、まずcURL自体の通信エラーか、APIから返されたHTTPエラーかを分けて考えます。curl_exec()がfalseを返した場合は、DNSやTLS、タイムアウトなど、通信の段階で失敗しています。
一方、HTTP 4xxや5xxの応答を受け取った場合、curl_exec()はレスポンス本文を返します。HTTPエラーでもfalseにはならないため、curl_getinfo()でステータスコードを確認し、APIのエラー応答を調べます。
例えば、HTTP 403は権限によってリクエストが拒否された状態です。Groqでは、組織やプロジェクトのモデル利用設定で対象モデルが制限されている場合も403になります。APIキーを作り直す前に、エラー本文にあるコードを確認し、利用したいモデルが許可されているかを調べます。
HTTP 429は、リクエスト数やトークン数などのレート制限に達したときに返ります。制限値はモデルやプランにより異なります。レスポンスのRetry-Afterやレート制限ヘッダーを確認し、無条件にリクエストを繰り返さないようにします。詳しくはGroqのRate Limitsを参照してください。
このサンプルは例外メッセージを表示するコマンドライン用です。Webアプリケーションに組み込む場合、APIキー、リクエスト本文、内部向けのエラー詳細を利用者の画面へそのまま出さず、必要な情報だけをサーバー側のログへ記録してください。
JSONを返す場合の注意点
モデルにJSON形式の応答を求める場合は、リクエストにresponse_formatを指定できます。JSON Object Modeを使う例は次のとおりです。
$requestBody = json_encode([
'model' => $modelId,
'messages' => [
[
'role' => 'user',
'content' => 'PHPのcURL拡張の用途を、{"summary":"説明"}の形式で説明してください。',
],
],
'response_format' => ['type' => 'json_object'],
], JSON_THROW_ON_ERROR);
JSON Object Modeは、JSONとして読み込める形式を求めるものです。キーや値の型まで指定したスキーマどおりになる保証とは異なります。PHP側でもjson_decode()で解析し、必要なキーや値の型を検証してください。スキーマに沿った出力が必要な場合は、利用モデルが対応しているかを確認したうえでStructured Outputsを検討します。設定方法と対応モデルはGroq公式のStructured Outputsで確認できます。
json_encode()とjson_decode()にJSON_THROW_ON_ERRORを指定すると、JSON処理に失敗したとき例外で検知できます。形式が正しいことと、アプリケーションが必要とするデータであることは別に検証しましょう。
まとめ
PHPからGroq APIを使うときは、環境変数からAPIキーとモデルIDを読み込み、cURLでChat Completions APIへJSONを送信できます。失敗時は、cURLの通信エラーとHTTPエラーを分けて確認します。特に403はモデル利用権限、429はレート制限も原因になるため、エラーコードや応答ヘッダーとGroqCloud側の設定を確認してください。
モデルや利用条件は変わることがあります。実装時には、現在の対応モデル、APIパラメーター、レート制限を公式資料で確認してから利用しましょう。
参考資料
- Groq API Reference:Chat Completions APIとレスポンス形式
- Groq Supported Models:利用可能なモデル一覧
- Groq Model Permissions:モデル利用権限
- Groq Rate Limits:レート制限と応答ヘッダー
- Groq API Error Codes and Responses:HTTPエラーとエラーコード
- Groq Structured Outputs:JSON Object Modeとスキーマ出力
- PHPマニュアル:curl_exec()
- PHPマニュアル:curl_getinfo()
- PHPマニュアル:json_encode()
- PHPマニュアル:json_decode()
奈良市を拠点に、27年以上の経験を持つフリーランスWebエンジニア、阿部辰也です。
これまで、ECサイトのバックエンド開発や業務効率化システム、公共施設の予約システムなど、多彩なプロジェクトを手がけ、企業様や制作会社様のパートナーとして信頼を築いてまいりました。
【制作会社・企業様向けサポート】
Webシステムの開発やサイト改善でお困りの際は、どうぞお気軽にご相談ください。小さな疑問から大規模プロジェクトまで、最適なご提案を心を込めてさせていただきます。
ぜひ、プロフィールやWeb制作会社様向け業務案内、一般企業様向け業務案内もご覧くださいね。
LaravelとMailpit APIでメール送信を自動テストする:宛先・件名・本文の確認
2026.11.18
LaravelからSMTPで送ったメールをMailpit APIで検索・取得し、宛先・件名・本文をPHPUnitで照合する方法を紹介します。メールFakeとの使い分け、識別値によるメールの取り違え防止、期限付きの受信待ち、APIエラーの切り分けも説明します。
Windows版PHPで拡張DLLを読み込めないときの原因と確認手順
2026.11.17
Windows版PHPで「Unable to load dynamic library」が出るときの確認手順を解説します。実行中のPHPとphp.ini、拡張DLLの配置先・互換条件・依存DLLを順に確認。intl拡張の検証例を通じて、DLL本体が存在しても読み込めない場合や、終了コードが0でも読み込みに失敗する場合を紹介します。
XAMPPのPHP更新時にphp.iniをどう移行する? 引き継ぐ設定と確認方法
2026.11.12
XAMPPでPHPを更新する際のphp.iniの移行方法を解説します。旧設定と新しい設定例を比較し、引き継ぐ項目や変更が必要な項目を整理。拡張・パス・エラー出力・アップロード・セッションなどの注意点と、CLI・Apacheそれぞれで設定の反映を確認する方法を紹介します。
PHPでフリガナ欄の入力を検証する:全角ハイフン・長音・カタカナの扱い
2026.11.11
住所のフリガナ欄で、全角ハイフンを入力したつもりなのにエラーになることがあります。見た目が似たハイフンや長音の違いを確認し、PHPでカナや英数字を変換してから検証する方法を紹介します。入力を保持したエラー表示や、変換後の値を確認する方法も解説します。