基本概念
Moss APIのモデル識別子、入力形式、リクエストの実行方式、レスポンスの返し方を理解します。
モデルとシナリオ
連携する際は、まずビジネスシナリオからモデルを選択します。シナリオガイドでは推奨される呼び出し方法とコピーして使えるサンプルを、APIリファレンスでは完全なリクエストパラメータ、戻り値、エラーの説明を提供しています。
| シナリオ | 実際の呼び出し方法 |
|---|---|
| 単一話者の音声生成 | model=moss-tts-1.5-flash |
| 複数話者の文字起こし | model=moss-transcribe-diarize-pro |
| 画像・動画の理解 | model=moss-vl-1.0 |
入力方法
エンドポイントによって受け付ける入力方法は異なります。テキストと設定は通常JSONリクエストボディに含めます。ローカルファイルを直接アップロードする場合はmultipart/form-dataを使用します。アップロード済みまたはホストされているファイルは、file_idまたはURLで参照できます。
| 方法 | 説明 | 主な用途 |
|---|---|---|
| JSONフィールド | リクエストボディでテキスト、パラメータ、参照IDを直接渡します | TTS input、VL input_text、voice_id |
| ローカルファイル | APIで指定されたファイルフィールド（fileなど）でアップロードします。ボイスの作成にはaudio_sampleを使用します | 音声の文字起こし、ボイスの作成、ファイルのアップロード |
file_id | 先にファイルをアップロードし、各機能のAPIで再利用します | 音声の文字起こし、マルチモーダル理解 |
| URL | パブリックURLまたはオブジェクトストレージのURLを渡します。サーバー側からアクセスできる必要があります | 音声の文字起こし、マルチモーダル理解 |
voice_id
voice_idは音声生成で使用するボイスの一意な識別子です。TTSとTTSDはボイスIDのみを受け付け、voice_url、voice_data、インライン音声、参照音声をボイスの入力として受け付けません。
| 取得方法 | 説明 |
|---|---|
| ボイス一覧の取得 | GET /v1/audio/voicesを呼び出して、現在のアカウントで利用可能なボイスを取得します。 |
| ボイスの作成 | POST /v1/audio/voicesを呼び出して参照音声をアップロードし、新しいボイスを生成します。 |
| ボイスライブラリからのコピー | MosslandボイスライブラリでボイスカードのIDをコピーします。 |
同期、非同期、ストリーミング
同期、非同期、ストリーミングは、それぞれ異なる実行方式です。ストリーミングは非同期と同じではなく、双方向のリアルタイム対話とも異なります。
| 方式 | 説明 | 適したシナリオ |
|---|---|---|
| 同期 | リクエストの接続を維持し、処理が完了すると結果を直接返します。 | 短いテキストのTTS、短い音声の文字起こし、画像理解 |
| 非同期 | async=trueを渡してタスクを作成します。task_idで完全な結果を照会し、必要に応じてwebhook_urlで最終状態の通知を受け取れます。 | 比較的長い音声生成、比較的長い音声処理 |
| ストリーミング | stream=trueを渡すと、サーバー側が音声チャンクまたはイベントを継続的に返します。 | 低レイテンシのTTS、文字起こしイベントのリアルタイム返却 |
エンドポイントがストリーミングに対応している場合、APIリファレンスのリクエストパラメータにstream、stream_format、対応するレスポンスイベントが明記されています。通常、stream=trueとasync=trueは同時に渡さないでください。
レスポンスタイプと読み取り方法
エンドポイントによって返されるオブジェクトは異なります。クライアントは該当するリファレンスに従って必要なフィールドを読み取り、使用しない互換フィールドは無視してください。
| レスポンスタイプ | 読み取り方法 |
|---|---|
| 音声バイナリ | Content-Typeがaudio/*の場合は、レスポンスボディを直接読み取って音声を保存または再生します。JSONとして解析しないでください。 |
| 音声結果JSON | status=SUCCESSを確認してからurlを読み取り、生成された音声を取得します。結果ファイルは速やかにダウンロードしてください。 |
| 非同期作成JSON | task_idとretry_afterを読み取り、GET /v1/audio/tasks/{task_id}を呼び出してタスクを照会します。 |
| タスク照会JSON | statusでタスクの状態を判断します。成功した場合は機能に応じてurl、text、またはsegmentsを読み取り、失敗した場合はerrorを読み取ります。 |
| 文字起こしJSON | 通常の文字起こしではtextを読み取ります。話者分離の結果ではtextとsegmentsを読み取ります。 |
| Responses APIオブジェクト | status=completedを確認してからoutput[].content[].textを読み取ります。status=incompleteの場合はincomplete_detailsを確認します。 |
| SSEイベントストリーム | Content-Typeがtext/event-streamの場合は、各data:内のJSONを順番に解析し、typeに応じて増分イベントと終了イベントを処理します。 |
| エラーJSON | リクエストが失敗した場合は、error.code、error.message、error.paramなどのフィールドを読み取って問題を特定します。 |
エラーとトラブルシューティング
| 現象 | 主な原因 |
|---|---|
| 400 | リクエスト構造、フィールド値、ファイル数、または入力形式が要件を満たしていません。 |
| 401 | APIキーがない、誤っている、または無効になっています。 |
| 403 | アカウント権限、モデル権限、またはセキュリティポリシーによる制限です。 |
| 404 | リクエストしたリソースが存在しません。 |
| 413 | ファイルまたはリクエストボディが上限を超えています。 |
| 429 | リクエスト頻度または同時実行数が上限を超えています。 |
| 5xx | サーバー側または上流モデルの異常です。エラーメッセージに従って再試行するか、サポートにお問い合わせください。 |
トラブルシューティングの際は、まずエンドポイント、モデル、入力方法、ファイルサイズ、URLのアクセス可否、エラーボディ内のerror.codeを確認してください。完全なエラー構造はエラーコードを参照してください。