实时

实时令牌、频道、发布与在线状态。

概览

基础路径: https://api.infrai.cc/v1/realtime

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/realtime capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/realtime/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

方法

realtime.token.issue

POST /v1/realtime/token/issue

签发限定频道与能力的客户端令牌。

参数

名称	类型	必填	说明
`user_id`	`string`	可选	连接用户的 id。
`channels`	`string[]`	可选	令牌可访问的频道。
`ttl_seconds`	`number`	可选	过期前的有效时长（秒）。

RealtimeToken { token, client_id, expires_at, endpoint }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/token/issue \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "user_42", "channels": ["room-42"], "capabilities": ["subscribe", "presence"], "ttl_seconds": 3600}'

realtime.channel.create

POST /v1/realtime/channel/create

创建实时频道。

参数

名称	类型	必填	说明
`name`	`string`	必填	频道名称。
`type`	`"public" \| "private" \| "presence"`	可选	频道可见性类型。

{ channel_id, name, type }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/channel/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "room-42", "type": "presence"}'

realtime.publish

POST /v1/realtime/publish

向频道发布事件。

参数

名称	类型	必填	说明
`channel`	`string`	必填	频道名称。
`event`	`string`	必填	事件名称。
`data`	`unknown`	必填	要发布的事件负载。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

{ message_id }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "room-42", "event": "message", "data": {"text": "hi"}}'

realtime.presence.get

GET /v1/realtime/presence/get/{channel}

获取频道当前的在线成员。

参数

名称	类型	必填	说明
`channel`	`string`	必填	频道名称。

{ members: Array<{ client_id, user_id? }> }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/realtime/presence/get/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

realtime.auth.sign

POST /v1/realtime/auth/sign

为指定频道签发厂商原生的频道授权签名（Pusher / Ably / Liveblocks），交给浏览器或移动端客户端使用。

参数

名称	类型	必填	说明
`client_id`	`string`	必填	签名令牌绑定的客户端身份标识。
`channels`	`string[]`	必填	要授权的频道列表；Pusher 只签第一个，Ably 全部签发。
`capabilities`	`string[]`	可选	授予的能力位，限定在 RealtimeCapability 封闭集合内，默认 subscribe。
`vendor`	`string`	可选	覆盖已配置的实时厂商（ably / pusher / liveblocks）。
`ttl_seconds`	`number`	可选	请求的有效期秒数，会被收敛到 MAX_TTL_SECONDS 上限。
`socket_id`	`string`	可选	Pusher 必填：客户端连接的 socket id。
`channel_data`	`Record<string, unknown>`	可选	presence 频道必填：写入在线名册的成员身份与状态。
`idempotency_key`	`string`	可选	幂等键，用于安全重试，避免重复签发。

VendorTokenResult { vendor, token }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/auth/sign \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "...", "channels": []}'

realtime.channel.get

GET /v1/realtime/channel/get/{channel}

获取单个实时频道的详情，包括类型、厂商、在线人数等。

参数

名称	类型	必填	说明
`channel`	`string`	必填	要查询的频道名。

Channel { channel_id, name, type, vendor, created_at, member_count?, last_published_at? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/realtime/channel/get/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

realtime.channel.delete

DELETE /v1/realtime/channel/delete/{channel}

删除一个实时频道并断开其订阅者。

参数

名称	类型	必填	说明
`channel`	`string`	必填	要删除的频道名。
`idempotency_key`	`string`	可选	幂等键，用于安全重试。

ChannelDeleteResult { channel, deleted, status }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/realtime/channel/delete/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

realtime.channel.list

GET /v1/realtime/channel/list

分页列出当前账户下的实时频道。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	翻页游标，传入上一页返回的 next_cursor。
`limit`	`number`	可选	单页返回的最大条数。

ChannelListResult { channels: Channel[], next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/realtime/channel/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

realtime.event.types

GET /v1/realtime/event/types

列出可订阅的实时事件类型封闭集合。

EventTypesResult { types: string[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/realtime/event/types \
  -H "Authorization: Bearer $INFRAI_API_KEY"

realtime.publish.batch

POST /v1/realtime/publish/batch

在一次调用中向多个频道批量发布消息。

参数

名称	类型	必填	说明
`messages`	`Array<{ channel: string; event: string; data: unknown }>`	必填	要发布的消息列表，每条含 channel、event 和 data。
`idempotency_key`	`string`	可选	幂等键，用于安全重试，避免重复发布。

PublishBatchResult { published }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/publish/batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": []}'

realtime.token.revoke

POST /v1/realtime/token/revoke

吊销先前签发的订阅令牌（登出或封禁时使用）。

参数

名称	类型	必填	说明
`token_or_jti`	`string`	必填	完整令牌或其 jti 标识。
`idempotency_key`	`string`	可选	幂等键，用于安全重试。

TokenRevokeResult { revoked }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/token/revoke \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token_or_jti": "..."}'

realtime.user.disconnect

POST /v1/realtime/user/disconnect

强制将某客户端踢下线，可选限定到单个频道。

参数

名称	类型	必填	说明
`client_id`	`string`	必填	要断开连接的客户端身份标识。
`channel`	`string`	可选	将断开限定到此频道；省略则全部断开。
`idempotency_key`	`string`	可选	幂等键，用于安全重试。

UserDisconnectResult { disconnected }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/realtime/user/disconnect \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "..."}'

全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

能力	端点	说明
`realtime.auth.sign`	`POST /v1/realtime/auth/sign`	Issue a vendor-native channel authorization signature (Pusher/Ably/Liveblocks) for client auth (not PDF signing — see pdf.sign).
`realtime.channel.create`	`POST /v1/realtime/channel/create`	Create a realtime pub/sub channel; idempotent.
`realtime.channel.delete`	`DELETE /v1/realtime/channel/delete/{channel}`	Delete a realtime channel and disconnect its subscribers.
`realtime.channel.get`	`GET /v1/realtime/channel/get/{channel}`	Get a single realtime channel's details (type, vendor, online count, etc.).
`realtime.channel.list`	`GET /v1/realtime/channel/list`	List the account's realtime channels with pagination.
`realtime.event.types`	`GET /v1/realtime/event/types`	List the closed set of subscribable realtime event types.
`realtime.presence.get`	`GET /v1/realtime/presence/get/{channel}`	Get the current presence state of members online in a channel.
`realtime.publish`	`POST /v1/realtime/publish`	Publish an event message to a realtime pub/sub channel.
`realtime.publish.batch`	`POST /v1/realtime/publish/batch`	Publish messages to multiple channels in a single batch call.
`realtime.token.issue`	`POST /v1/realtime/token/issue`	Issue a short-lived infrai-HMAC client auth token for pub/sub realtime channels (NOT for AI voice sessions — see ai.voice.session).
`realtime.token.revoke`	`POST /v1/realtime/token/revoke`	Revoke a previously issued subscription token (e.g., on logout or ban).
`realtime.user.disconnect`	`POST /v1/realtime/user/disconnect`	Forcibly disconnect a client, optionally scoped to a single channel.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) realtime.token.issue
curl -X POST https://api.infrai.cc/v1/realtime/token/issue \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "user_42", "channels": ["room-42"], "capabilities": ["subscribe", "presence"], "ttl_seconds": 3600}'

# 3) realtime.channel.create
curl -X POST https://api.infrai.cc/v1/realtime/channel/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "room-42", "type": "presence"}'

# 4) realtime.publish
curl -X POST https://api.infrai.cc/v1/realtime/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "room-42", "event": "message", "data": {"text": "hi"}}'

# 5) realtime.presence.get
curl -X GET https://api.infrai.cc/v1/realtime/presence/get/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) realtime.auth.sign
curl -X POST https://api.infrai.cc/v1/realtime/auth/sign \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "...", "channels": []}'

# 7) realtime.channel.get
curl -X GET https://api.infrai.cc/v1/realtime/channel/get/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 8) realtime.channel.delete
curl -X DELETE https://api.infrai.cc/v1/realtime/channel/delete/CHANNEL \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 9) realtime.channel.list
curl -X GET https://api.infrai.cc/v1/realtime/channel/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"