はじめに

Sarashina API の基本仕様からクイックスタート、認証方法、レート制限、エラーハンドリングまでを包括的に解説する総合ガイドです。

クイックスタート

Sarashina API を初めてご利用いただく方のために、最初の APIリクエストを送信するまでの最短手順をご紹介します。

1. API キーの取得

Sarashina API コンソールにアクセスし、ログインしてください。
「API Keys」セクションで 新しい API キーを作成 をクリックします。
発行されたキーをコピーし、安全な場所に保管してください。

2. 環境変数の設定

取得した API キーを環境変数 SARASHINA_API_KEY に設定します。

export SARASHINA_API_KEY="your_api_key_here"

3. リクエスト送信例

ターミナルから以下のコマンドを実行して、sarashina3-mini モデルでリクエストを送信します。

curl https://api.sarashina.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SARASHINA_API_KEY}" \
  -d '{
    "model": "sarashina3-mini",
    "messages": [
      {
        "role": "user",
        "content": "Sarashina をテーマにした短い物語を書いてください"
      }
    ]
  }'

認証

Sarashina API では、APIキーを用いたBearer認証を採用しています。すべてのリクエストには、有効な APIキーを Authorization HTTP ヘッダーに含めていただく必要があります。

認証ヘッダー

リクエスト送信時には、以下のように Authorization ヘッダーへ Bearer <API_KEY> の形式で API キーをご指定してください。

Authorization: Bearer YOUR_API_KEY

API キーの管理とセキュリティ

秘密の保持: API キーは秘密情報です。第三者と共有したり、ブラウザやモバイルアプリなどのクライアントサイドコードに露出させたりしないでください。
サーバーサイドでの実行: リクエストは必ずバックエンドサーバー等の保護された環境から実行してください。
リポジトリの保護: ソースコードをバージョン管理にコミットする際は、.env ファイルを .gitignore に含め、API キーが誤って公開リポジトリへコミットされないよう注意してください。

レート制限

Sarashina API では、サービスの安定性と公平な利用を実現するため、契約主体とモデルの組み合わせごとにレート制限（Rate Limits）を設定しています。レート制限は、各モデルクラスごとに1分あたりのリクエスト数（RPM）で管理されています。いずれかの制限を超えた場合、429 Too Many Requests エラーが返されます。

ベストプラクティス

バックオフとリトライ: 429 エラーを検知した場合、数秒間待機してからリクエストを再送する指数バックオフ（Exponential Backoff）アルゴリズムを導入してください。
呼び出し間隔の調整: 短時間に集中した大量リクエストを避け、呼び出し間隔の調整を行ってください。

エラー

API呼び出し中にエラーが発生した場合、Sarashina APIは状況に応じたHTTP ステータスコードを返します。詳細な原因はレスポンスボディのメッセージをご確認いただき、必要に応じてログやドキュメントをご参照ください。

HTTPステータスコード一覧

HTTP ステータスコード	エラー内容	主な原因と対応
400	Bad Request	パラメータ不正、サポート外の値・型・範囲外の指定 → 詳細
401	Unauthorized	APIキーの未指定、または無効なキーを使用 → 詳細
404	Not Found	エンドポイントURLの誤り → 詳細
413	Payload Too Large	リクエストサイズ超過（上限はエンドポイントにより異なる） → 詳細
429	Too Many Requests	レート制限超過 → 詳細
500 / 503	Server Error	サーバー内部エラー・メンテナンス → 詳細

—

エラーレスポンス形式の例

標準的なエラー応答 (JSON)

4xx / 5xx エラー発生時には、以下の形式でエラー内容が返却されます。

{
  "message": "Bad Request"
}

（上記は 400 Bad Request の例です。400 エラー発生時の message には "Bad Request" または "Invalid JSON or disallowed fields"（リクエスト JSON の形式不正、または未サポートのパラメータが指定された場合）など、原因に応じたメッセージが設定されます。）

エラー詳細

`400 Bad Request`

原因: リクエストの形式や内容に問題があった（パラメータ不正等）場合に返却されます。
対応: APIリファレンスを参照し、必須パラメータやJSONのデータ型、値の範囲が正しく指定されているか確認してください。

`401 Unauthorized`

原因: APIキーの未指定、または無効なキーを使用した場合に返却されます。
対応: ヘッダーの Authorization: Bearer <API_KEY> の設定内容をご確認ください。

`404 Not Found`

原因: リクエスト先の URL（エンドポイント）が存在しないか、間違っている場合に返却されます。
対応: APIリファレンスを参照し、エンドポイント URL（例: https://api.sarashina.ai/v1/chat/completions）が正しいかご確認ください。

`413 Payload Too Large`

原因: リクエストのデータ容量が上限を超過した場合に返却されます。上限はエンドポイントごとに異なり、Chat Completions・Embeddings・Rerank は 4MiB（4,194,304 バイト）、Translate は 1MiB（1,048,576 バイト）です。
対応: 入力テキストやリクエストボディのサイズを小さくして再試行してください。

`429 Too Many Requests`

原因: レートリミット（利用制限）を超過した場合に応答されます。
対応: このエラーが発生した場合は、一定時間（数秒）待機してからリクエストを再送するか、呼び出し間隔を調整するなどの実装を行ってください。

`500 Internal Server Error` / `503 Service Unavailable`

原因: API サーバー内部で一時的な障害またはメンテナンスが発生した場合に返却されます。
対応: 時間をおいてリクエストを再試行してください。最新のシステム稼働状況や障害情報は status.sarashina.ai にて公開しています。障害が継続する場合はお問い合わせください。

エラーハンドリングのベストプラクティス

ステータスコードのチェック APIからのレスポンスを受け取った際は、まずHTTPステータスコードを確認し、200番台（成功）以外の場合はエラーとして処理を分岐させてください。
レスポンスボディの解析 エラーの具体的な理由を特定するため、レスポンスボディに含まれるメッセージを出力・記録する実装を推奨します。
リトライ制御（429エラー対策） 429 Too Many Requests に対しては、ただちに再リクエストするのではなく、一定秒数待機する仕組み（エクスポネンシャルバックオフ等）を導入してトラフィックを調整してください。

概要 Chat Completions