メインコンテンツへスキップ
このAPIはClient SDKキー（osk_プレフィックス）で認証します。 REST APIチャット（OpenAI互換）とは別のエンドポイントです。

​
メッセージ送信

POST /v1/chat/{persona_id}
ペルソナにメッセージを送信します。thread_idを省略すると新しいスレッドが作成され、含めると既存のスレッドを続行します。 利用可能なモデルはGET /v1/modelsで確認できます。

​
リクエスト

新規スレッド（model必須）： 
{
  "model": "shopping-assistant",
  "messages": [
    {
      "role": "user",
      "content": "今晩のメニューは何がいいかな？"
    }
  ]
}
スレッド続行（model不要）： 
{
  "thread_id": "thr_a1b2c3d4e5f6",
  "messages": [
    {
      "role": "user",
      "content": "カレーの材料を教えて"
    }
  ]
}
フィールドタイプ必須説明
modelstring新規スレッド時必須モデル名（GET /v1/modelsから取得）
thread_idstringX既存スレッドID（省略時は新規スレッド作成）
messagesarrayOメッセージ配列
messages[].rolestringOuser
messages[].contentstringOメッセージ内容
新規スレッド作成時に指定したモデルはそのスレッドに固定されます。以降の会話ではmodelフィールドを省略しても同じモデルが使用されます。

​
レスポンス

{
  "success": true,
  "data": {
    "thread_id": "thr_a1b2c3d4e5f6",
    "is_new_thread": true,
    "user_message": {
      "message_id": "msg_u1v2w3x4y5z6",
      "role": "user",
      "content": "今晩のメニューは何がいいかな？",
      "created_at": "2026-04-16T10:00:00Z"
    },
    "assistant_message": {
      "message_id": "msg_a7b8c9d0e1f2",
      "role": "assistant",
      "blocks": [
        {
          "type": "text",
          "content": "雨の日にはあたたかいビーフカレーはいかがですか？"
        },
        {
          "type": "product_list",
          "title": "ピリ辛ビーフカレーの材料",
          "badge": "AI おすすめ",
          "items": [
            { "id": "p_001", "name": "和牛ロース (300g)", "section": "精肉コーナー", "price": 24500 },
            { "id": "p_002", "name": "有機じゃがいも/にんじんセット", "section": "新鮮野菜", "price": 4800 }
          ],
          "actions": [
            { "id": "view_recipe", "label": "詳細を見る", "style": "primary" },
            { "id": "show_alternates", "label": "他のおすすめを見る", "style": "secondary" }
          ]
        },
        {
          "type": "suggestion",
          "content": "カレーに合う赤ワインもおすすめしましょうか？",
          "actions": [
            { "id": "wine_yes", "label": "おすすめして", "style": "primary" },
            { "id": "wine_no", "label": "大丈夫です", "style": "secondary" }
          ]
        }
      ],
      "created_at": "2026-04-16T10:00:01Z"
    }
  }
}

​
ブロックタイプ

assistantレスポンスは構造化されたblocks配列で返されます。
タイプ説明主なフィールド
textテキストメッセージcontent
image画像url
product_list商品リストtitle, items[], actions[]
suggestionAIおすすめ/提案content, actions[]

​
アクション

ブロックに含まれるactionsは、クライアントでユーザーインタラクションを処理するための情報です。
フィールド説明
idアクション識別子
labelボタンテキスト
styleprimary / secondary / text

​
スレッド情報取得

GET /v1/chat/{persona_id}/threads/{thread_id}
スレッドのメタ情報を取得します（メッセージ本文は含まれません）。

​
レスポンス

{
  "success": true,
  "data": {
    "thread_id": "thr_a1b2c3d4e5f6",
    "title": "今晩のメニューおすすめ",
    "status": "ACTIVE",
    "message_count": 4,
    "started_at": "2026-04-16T10:00:00Z",
    "last_active_at": "2026-04-16T10:30:00Z"
  }
}
ステータス説明
ACTIVE進行中
CLOSED終了済み

​
スレッド終了

POST /v1/chat/{persona_id}/threads/{thread_id}/close
スレッドを終了します。ペルソナのステータスがCHAT → READYに遷移します。

​
レスポンス

{
  "success": true,
  "data": {
    "thread_id": "thr_a1b2c3d4e5f6",
    "thread_status": "CLOSED",
    "persona_status": "READY",
    "closed_at": "2026-04-16T10:35:00Z"
  }
}
既に終了したスレッドにリクエストすると409 Conflictが返されます： 
{
  "success": false,
  "error": {
    "code": "ALREADY_CLOSED",
    "message": "thread is already closed"
  }
}

​
メッセージ一覧取得

GET /v1/chat/{persona_id}/threads/{thread_id}/messages
スレッドのメッセージ一覧を取得します（古い順）。カーソルベースのページネーションに対応しています。

​
クエリパラメータ

パラメータタイプデフォルト説明
limitinteger50返すメッセージ数（最大100）
beforestring-このmessage_idより前のメッセージを読み込み（逆方向ページング）

​
レスポンス

{
  "success": true,
  "data": {
    "thread_id": "thr_a1b2c3d4e5f6",
    "messages": [
      {
        "message_id": "msg_u1v2w3x4y5z6",
        "role": "user",
        "content": "今晩のメニューは何がいいかな？",
        "created_at": "2026-04-16T10:00:00Z"
      },
      {
        "message_id": "msg_a7b8c9d0e1f2",
        "role": "assistant",
        "blocks": [
          { "type": "text", "content": "ビーフカレーはいかがですか？" }
        ],
        "created_at": "2026-04-16T10:00:01Z"
      }
    ],
    "has_more": false,
    "next_before": null
  }
}
has_moreがtrueの場合、next_beforeの値をbeforeパラメータに渡して次のページを読み込みます。

​
全体フロー例

# 1. ペルソナ作成
PERSONA_ID=$(curl -s -X POST https://api.ones1ght.com/v1/persona \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "田中太郎", "locale": "ja"}' | jq -r '.data.persona_id')

# 2. 利用可能なモデルを確認
curl -s https://api.ones1ght.com/v1/models \
  -H "Authorization: Bearer $SDK_KEY"

# 3. チャット開始（新規スレッド自動作成、model必須）
THREAD_ID=$(curl -s -X POST https://api.ones1ght.com/v1/chat/$PERSONA_ID \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "shopping-assistant", "messages": [{"role": "user", "content": "今晩何食べようかな？"}]}' | jq -r '.data.thread_id')

# 4. 会話を続ける（model不要、スレッドに固定済み）
curl -X POST https://api.ones1ght.com/v1/chat/$PERSONA_ID \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"thread_id\": \"$THREAD_ID\", \"messages\": [{\"role\": \"user\", \"content\": \"カレーの材料を教えて\"}]}"

# 5. メッセージ履歴を取得
curl https://api.ones1ght.com/v1/chat/$PERSONA_ID/threads/$THREAD_ID/messages \
  -H "Authorization: Bearer $SDK_KEY"

# 6. スレッド終了
curl -X POST https://api.ones1ght.com/v1/chat/$PERSONA_ID/threads/$THREAD_ID/close \
  -H "Authorization: Bearer $SDK_KEY"