Skip to main content
Realtime

Conversation の作成

リアルタイムの音声・テキスト対話およびバックグラウンドタスクイベントに使用する Conversation を作成します。

Realtime は現在 Beta 機能です。API 定義、イベント構造、および動作は変更される可能性があります。ドキュメントの更新を確認し、本番環境で使用する前に互換性を検証してください。
POST /api/v1/forward/realtime/conversations

ヘッダー

Header必須説明
AuthorizationはいBearer <PAT または SAT>
Content-Typeはいapplication/json
Idempotency-Keyはいアプリケーションが生成する作成操作の識別子です。先頭または末尾に空白を含まない 1～256 バイトの値を指定します。UUID を推奨します。同じ操作を再試行する場合は、同じ値とリクエストボディを再利用してください。

リクエストボディ

パラメーター型必須説明
identity_idstringはい現在の認証スコープ内でアクセスできる有効な Identity ID。先頭または末尾の空白や制御文字を含まない 1～128 文字の値です。
template_idstringはい現在の認証スコープ内でアクセスできる Template ID。先頭または末尾の空白や制御文字を含まない 1～128 文字の値です。
titlestring または nullいいえデフォルトは null。前後の空白を削除した後で 1～256 文字とし、制御文字は使用できません。
metadataobject または nullいいえデフォルトは {}。null は {} として扱われます。正規化して保存されるテキストは 16 KiB 以下で、U+0000 を含めることはできません。
configobjectいいえConversation の Realtime 設定。省略すると、サービスがデフォルト設定を解決します。null は使用できません。
config.audioobjectいいえ音声設定。
config.audio.outputobjectいいえ出力音声設定。
config.audio.output.voicestringいいえプリセット音声の識別子。次の表にある値のみ使用できます。作成後は固定され、変更できません。

プリセット音声

voice名前
longanqianデフォルト
longanlingxinLongan Lingxin
longanlingxiLongan Lingxi
longanxiaoxinLongan Xiaoxin
longanlufengLongan Lufeng

リクエスト例

IDEMPOTENCY_KEY="$(uuidgen)"

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/realtime/conversations" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "identity_id": "idn_xxx",
    "template_id": "tmpl_xxx",
    "title": "プロジェクト分析",
    "metadata": {"source": "desktop"},
    "config": {
      "audio": {
        "output": {
          "voice": "longanlingxin"
        }
      }
    }
  }'

レスポンス例

HTTP 201 Created 
{
  "id": "conv_xxx",
  "type": "voice.conversation",
  "status": "ready",
  "title": "プロジェクト分析",
  "metadata": {
    "source": "desktop"
  },
  "config": {
    "audio": {
      "output": {
        "voice": "longanlingxin"
      }
    }
  },
  "created_at": "2026-08-31T02:00:00Z",
  "updated_at": "2026-08-31T02:00:01Z"
}

レスポンスフィールド

フィールド型説明
idstringConversation ID。
typestring常に voice.conversation。
statusstring作成に成功した場合は ready。
titlestring または nullConversation のタイトル。
metadataobjectビジネスメタデータ。
configobjectサービスが解決して保存した、完全な有効設定。
config.audio.output.voicestringConversation に固定された出力音声。
created_atstringRFC 3339 形式の作成日時。
updated_atstringRFC 3339 形式の更新日時。

冪等な再試行

  • 同じ Idempotency-Key と同じリクエストボディを使用すると、最初の作成結果が再送されます。
  • 再送されたレスポンスには Idempotency-Replayed: true が含まれます。
  • 同じ Idempotency-Key を異なるリクエストボディで使用すると、409 idempotency_conflict が返されます。
  • 最初のリクエストが処理中の場合は 409 idempotency_key_in_progress が返されます。再試行までの間隔は Retry-After を参照してください。

エラー

HTTPCode発生条件
400invalid_request、invalid_identity_id、invalid_template_id、invalid_title、invalid_metadataリクエストパラメーターが無効です。
400invalid_voiceconfig.audio.output.voice がサポートされていません。
400invalid_idempotency_key冪等性ヘッダーがないか、無効です。
401authentication_required、ゲートウェイの TOKEN_INVALIDPAT または SAT が無効または期限切れであるか、Service Account Key が直接使用されています。
403permission_error、identity_mismatchSAT が利用可能な Workspace に紐付けられていないか、Identity スコープの SAT で別の Identity が指定されています。
404identity_not_found現在の認証スコープ内で Identity が見つかりません。
409idempotency_conflict同じキーを異なるリクエストに使用することはできません。
409idempotency_key_in_progress同じキーのリクエストが処理中です。再試行間隔は Retry-After を参照してください。
409conversation_not_ready、conversation_initialization_conflictConversation の準備ができていないか、初期化が競合しています。
422identity_disabledIdentity が無効です。
422conversation_initialization_failedConversation の初期化に失敗しました。
500conversation_persistence_error、conversation_state_invalid、template_config_read_failed、internal_errorサービス内部エラーが発生しました。
502forward_unavailable、forward_protocol_error依存サービスでエラーが発生しました。
503idempotency_unavailableサービスが一時的に利用できません。

関連項目

Conversation に接続

Session の作成

はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス