BytePlus ModelArk API 接続ガイド

地域、モデル有効化、認証を確認する

BytePlus International ModelArk の Chat API を OpenAI Python SDK から通常テキストに使う手順です。承認されたアカウント、対象地域の API キー、その地域で有効化した実モデル ID が必要です。地域、アカウント・プロジェクト、モデルの版、呼び出し方、請求条件を記録します。一覧で見えていても、そのアカウントで有効化済み、残高ありとは限りません。

本例は API キーの Bearer 認証です。AK/SK は別方式で、推論エンドポイント ID と署名の要件をその資料で確認する必要があります。AccessKey を本例の API キーに代入しないでください。カスタム推論エンドポイントを使う場合も ID と地域を別に確認します。Coding Plan の設定が本番バックエンドの認証・課金にそのまま使えるとは限りません。

地域 URL は厳密なデータ駐留の保証ではない

AP は https://ark.ap-southeast.bytepluses.com/api/v3 で、公式の地域名は Johor、ap-southeast-1 です。EU は https://ark.eu-west.bytepluses.com/api/v3、Dublin、eu-west-1 です。southeast を含むだけで AP をシンガポールのモデル拠点と説明しないでください。

キー、モデル有効化、推論エンドポイントは地域ごとに分離されています。コンソールも対象地域に切り替えて確認します。一方、地域資料には通常は近い地域を優先しつつ、AP と EU 間を含む別地域への振り分けがあり得るとあります。URL だけで地域内処理を保証せず、制限がある場合は適用可能な契約と方式を先に確認します。無断の代替経路で境界を越えないでください。

インストールと仮設定

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

ARK_API_KEY は承認されたサーバー環境から安全に供給します。例は AP 形式です。実際の地域に合わせ、別地域のキーを混用しないでください。Chat、通常テキスト、max_tokens 対応を確認して有効化済み ID を設定します。

export ARK_BASE_URL='https://ark.ap-southeast.bytepluses.com/api/v3'
export ARK_MODEL='YOUR-ACTIVATED-TEXT-MODEL-ID'

最小の非ストリーミング呼び出し

次を modelark_chat.py に保存し、権限と費用を確認して python modelark_chat.py を実行します。SDK はベースに /chat/completions を追加します。/openai/v1 や管理 API には置き換えません。出力128、30秒タイムアウト、再試行0は例の設定で、サービス容量や応答保証ではありません。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["ARK_BASE_URL"],
    api_key=os.environ["ARK_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
request = {
    "model": os.environ["ARK_MODEL"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print("finish_reason:", answer.choices[0].finish_reason)
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

返されたモデル、finish reason、usage を確認してから回答を評価します。打ち切り、フィルター、通常完了は区別します。HTTP200 だけでは品質、請求の帰属、地域条件の受入確認になりません。

テキストと状態を別々に解析する

対応モデルでは、非ストリーミング呼び出しを次に置き換えます。Chat は SSE と delta.content を使います。推論は reasoning_content、ツールは別の差分構造に入ることがあり、すべてを利用者向け回答に連結しないでください。Responses には別の解析が必要です。

usage = None
finish_reason = None
with client.chat.completions.create(**request, stream=True) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        choice = part.choices[0]
        if choice.delta.content:
            print(choice.delta.content, end="", flush=True)
        if choice.finish_reason is not None:
            finish_reason = choice.finish_reason
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

添字を使う前に choices を確認し、usage があれば別に保存します。ストリームで usage がない場合もあり、本例は全モデル共通の使用量オプションを仮定しません。最新のモデル API で確認してください。未取得は料金ゼロではありません。finish reason の後も必要なフレームを読み、中断は未完了と記録して状態確認後に再試行します。

障害調査と公開前の確認

• 認証・権限：キーの取得元、地域、プロジェクト権限、モデル有効化を確認する。認証情報を共有しない。
• 404・リソースなし：ベース、モデルまたはカスタムエンドポイント ID を確認し、地域間の取り違えを避ける。
• パラメーター：短いテキストから始め、出力、推論、ツールの対応項目を一つずつ加える。
• 制限・容量不足：クォータ、同時実行、アカウント状態を調べ、待機指示に沿った有限の再試行を行う。地域を盲目的に変えない。
• タイムアウト/5xx：機密情報を除いた番号、時刻、途中出力、終了状態を残し、外部操作の重複を防ぐ。

保存、ログ、越境処理、削除を実際の条件で確認します。SDK 互換を、保存なしや特定法域の適合と混同しないでください。モデル、入出力、キャッシュ、デプロイ、再試行、追加サービスを請求と照合します。出力、同時実行、全体時間を制限し、打ち切り、中断、権限拒否、使用量不足を検証します。

本例はオフライン構文と合成ストリームの確認のみです。キーの読み取り、モデル有効化、実サービス呼び出しは行っていません。利用可否、品質、請求は承認された環境で確認してください。

公式資料

確認日：2026-10-17。公開の地域・ストリーミング本文を確認済みです。使用前に現在の設定を確認してください。

• Base URL と認証
• 地域と振り分けの範囲
• クイックスタート
• ストリーミング
• エラーコード参照