AIものさし

GroqをOpenAI互換APIで使う方法｜接続先・モデル・権限を確認

Groqへ既存クライアントを接続するときのbase URL、キー、モデルID、未対応項目とモデル権限を確認。APIを実行しない静的例と診断順を示します。

AIものさし編集部

GroqをOpenAI互換のクライアントから使うなら、接続先URL、GroqのAPIキー、Groqで利用できるモデルIDをそろえます。OpenAIのライブラリを使えることと、OpenAI向けのモデル名や全パラメーターがそのまま使えることは別です。

この記事は、既存のテキスト生成処理をGroqのChat Completionsへ接続するための確認手順です。API呼出し、キー取得、認証、契約変更は行っていません。掲載Pythonは構文と設定項目だけをローカルで検査しており、接続成功を実測したコードではありません。

目次

最初に、接続先・キー・モデルを一組で確認する

Groqの公式互換資料は、OpenAIのclient libraryを使う場合、api_keyへGroqのキーを渡し、base_urlをhttps://api.groq.com/openai/v1へ変更する方法を案内しています。[Groq：OpenAI（新しいタブで開く） Compatibility](https://console.groq.com/docs/openai（新しいタブで開く）)

表は横にスクロールできます

項目確認する内容よくある取り違え
接続先GroqのOpenAI互換base URL既存の接続先が残る
認証利用を許可されたGroqのキー別サービスのキーを渡す
モデルGroq上の正確なモデルIDと利用条件別サービスの表示名を使う
リクエスト選んだAPIとモデルが受け付ける項目既存の設定を全部コピーする

まずアプリのどの設定から値が入るかを確認します。複数のproviderを切り替える構成なら、キーだけ替わってURLやモデルが前のまま、という組合せになっていないかを見ます。確認のために、キーの値をログや画面へ表示する必要はありません。

モデル一覧と廃止情報を合わせて読む

公式のSupported Modelsには、モデルID、Production／Previewの区分などが掲載されています。モデルを一覧に見つけたことだけで、自分の契約やprojectから使えるとは確定しません。Groq：Supported Models（新しいタブで開く）

特に古いサンプルは、廃止情報と合わせて確認します。2026年10月21日の資料では、llama-3.1-8b-instantとllama-3.3-70b-versatileは一覧にEnterprise表記で残る一方、廃止資料はfree／developer tierでの終了日を2026年8月16日とし、committed-spend契約のEnterpriseが対象外であることを説明しています。「一覧にあるから全員使える」「廃止欄にあるから全契約で使えない」のどちらにも広げません。Groq：Model Deprecation（新しいタブで開く）

Previewは評価用で、短い予告で終了し得るという説明もあります。本番の代替モデルを選ぶなら、名前だけ差し替えず、入力形式、出力、必要な機能、品質、費用、利用条件を確認します。過去の廃止告知に書かれた代替先も、現在利用できるかを再確認します。

最小のChat Completionsから確認する

次は、OpenAI Pythonクライアントを使う接続例です。実行には対応するopenaiパッケージと、自分の環境で設定したGROQ_API_KEY、GROQ_MODELが必要です。GROQ_MODELには、現在の契約とprojectで使用を確認したGroqのモデルIDを指定します。環境変数名をそのままモデル名として送る例ではありません。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.groq.com/openai/v1",
    api_key=os.environ["GROQ_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["GROQ_MODEL"],
    messages=[
        {"role": "user", "content": "Write one short greeting."}
    ],
)

print(response.choices[0].message.content)

この例を実行すればネットワーク要求が発生します。この記事の制作では実行せず、Pythonの構文、Groqのbase URL、参照する環境変数、リクエスト項目だけを静的に確認しました。実際に試す場合は、送信してよい短い入力と、利用量を確認できる環境で一件から始めます。

最初の確認には、tools、画像、独自の出力形式、複数候補などを同時に加えません。短いテキスト要求が通るかを見てから、用途に必要な設定を一つずつ加えると、どの項目で失敗したかを切り分けやすくなります。

互換性は、追加パラメーターごとに確認する

Groqの互換資料は、未対応項目としてlogprobs、logit_bias、top_logprobs、messages内のnameを挙げ、送ると400エラーになると説明しています。nを指定する場合は1でなければならない条件もあります。既存アプリや中間ライブラリが自動で加える項目まで確認します。

例えば、入力は同じでも、アプリが候補を複数生成するためにnを増やしているなら、その設定をそのまま移せるとは限りません。単純なリクエストでは動くが既存アプリでは失敗する場合、実際に送られる項目を、秘密情報を除いて比較します。

この説明は掲載のChat Completions接続確認の範囲です。Responses APIや音声API、モデルごとの機能へ、同じ対応表を無条件に流用しません。必要なAPIとモデルの現行仕様を確認してください。

403なら、組織とprojectのモデル権限も見る

公式のModel Permissionsは、組織とprojectで利用できるモデルを制限でき、制限されたモデルへの要求は403になると説明しています。組織でブロックされたモデルを、project側で許可して広げることはできません。Groq：Model Permissions（新しいタブで開く）

同資料には、組織側のmodel_permission_blocked_orgと、project側のmodel_permission_blocked_projectというcodeが示されています。errorのcodeと対象モデル、利用projectを確認し、必要なら管理者へ渡します。403だからといって、キーを作り直したり、組織の制限を一括で緩めたりする前提にしません。

モデルが存在すること、契約上使えること、組織で許可されること、projectで許可されることを分けます。別のprojectで成功した結果を、今の接続にもそのまま適用しないようにします。

三つの症状で、次の確認先を変える

以下は診断の設計例で、実際に発生させたエラーではありません。

表は横にスクロールできます

症状次に確認すること先にしないこと
古いサンプルのモデルで使えない正確なID、廃止日、対象契約、現在の代替先全契約で廃止と即断
最小例は通るが、既存アプリで400追加パラメーターと中間ライブラリの送信内容同じ要求を連続再試行
モデル権限の403とcodeが出る組織・projectの制限と利用中projectキー交換だけで解決すると判断

レスポンスの状態とmessage、code、発生時刻を残し、認証情報を除いて調べます。一般的なAPIエラーの分類はGroqのエラー資料（新しいタブで開く）で確認できます。空の文字列や固定の成功文へ置き換えて、接続できたように見せないでください。

アプリへ戻す前に、業務の出力を確認する

短い返答が来ても、業務処理が移行できたとは限りません。要約なら必要な情報が落ちないか、分類なら許可した値と未確認の扱い、tool利用なら必要な引数と外部操作の範囲を確認します。モデルを替えれば、同じpromptでも出力が変わる可能性があります。

記録には、APIの種類、base URL、モデルID、利用project、追加パラメーター、確認した入力と出力、残る未対応機能を残します。キーの値や顧客本文を共有メモへ貼らず、環境を識別できる情報だけに絞ります。

接続先・モデル・要求項目をそろえ、必要な出力を検証してから既存アプリへ戻します。互換ライブラリが使えることを、全機能・全モデル・全契約の互換性として扱わないことが、手戻りを減らす判断になります。

参考資料

公式資料の確認日：2026年10月21日。Pythonと三症状は説明用の例です。掲載コードは静的検査のみで、API要求、認証、実モデルの利用可否、生成品質、速度、料金、SDK動作は未検証です。