# コネクション API


## RequestKeyFrame

*バージョン 2024.2.0 で追加。*

**x-sora-target**: Sora_20241218.RequestKeyFrame

指定したチャネルで配信している接続に対してキーフレームを要求します。

この API は `role` が `sendrecv` または `sendonly` の接続にのみ有効です。

キーフレーム要求を送ってからキーフレームが送られてくるまでは、
1 秒間隔で最大 5 回までリクエストを送信します。

`channel_id` や `connection_id` が存在しない場合はエラーとなります。

| キー | 型 |
| --- | --- |
| channel_id | string |
| connection_id | string |
| rid (オプション) | string (r0 \| r1 \| r2) |

`rid` は Sora 2026.1.3 以降で指定できます。
サイマルキャスト利用時に、キーフレームを要求する RID を指定します。

`rid` を省略した場合は、視聴者が受信している RID を対象にします。
ただし、クラスターリレー、録画、RTP 転送のいずれかがある場合は、配信者が送信しているすべての RID を対象にします。

要求は、対象の RID を視聴する接続、クラスターリレー、録画、RTP 転送のいずれかがある場合に送信します。
配信者が送信していない RID には要求しません。
要求を送信しない場合も API は成功を返します。

サイマルキャストを利用していない配信者に `rid` を指定した場合は、省略した場合と同じ動作です。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20241218.RequestKeyFrame" \
    --json '{"channel_id":"sora","connection_id":"KDBN2YD1A919V5BA2JX6TG2RP8"}' \
    | jq .
{
    "channel_id": "sora",
    "connection_id": "KDBN2YD1A919V5BA2JX6TG2RP8"
}
```

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20241218.RequestKeyFrame" \
    --json '{"channel_id":"sora","connection_id":"KDBN2YD1A919V5BA2JX6TG2RP8","rid":"r1"}' \
    | jq .
{
    "channel_id": "sora",
    "connection_id": "KDBN2YD1A919V5BA2JX6TG2RP8",
    "rid": "r1"
}
```