Realtime

Realtime tokens, channels, publish and presence.

Overview

Base path: https://api.infrai.cc/v1/realtime

Auth header: 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"

Methods

realtime.token.issue

POST /v1/realtime/token/issue

Issue a client token scoped to channels and capabilities.

Parameters

Name	Type	Required	Description
`user_id`	`string`	Optional	Id of the connecting user.
`channels`	`string[]`	Optional	Channels the token may access.
`ttl_seconds`	`number`	Optional	Lifetime in seconds before expiry.

Returns

RealtimeToken { token, client_id, expires_at, endpoint }

Example

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

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

Create a realtime channel.

Parameters

Name	Type	Required	Description
`name`	`string`	Required	Channel name.
`type`	`"public" \| "private" \| "presence"`	Optional	Channel visibility type.

Returns

{ channel_id, name, type }

Example

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

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

Publish an event to a channel.

Parameters

Name	Type	Required	Description
`channel`	`string`	Required	Channel name.
`event`	`string`	Required	Event name.
`data`	`unknown`	Required	Event payload to publish.
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

{ message_id }

Example

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

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}

Get the members currently present on a channel.

Parameters

Name	Type	Required	Description
`channel`	`string`	Required	Channel name.

Returns

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

Example

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

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），交给浏览器或移动端客户端使用。

Parameters

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

Returns

VendorTokenResult { vendor, token }

Example

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

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}

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

Parameters

Name	Type	Required	Description
`channel`	`string`	Required	要查询的频道名。

Returns

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

Example

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

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}

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

Parameters

Name	Type	Required	Description
`channel`	`string`	Required	要删除的频道名。
`idempotency_key`	`string`	Optional	幂等键，用于安全重试。

Returns

ChannelDeleteResult { channel, deleted, status }

Example

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

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

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

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	翻页游标，传入上一页返回的 next_cursor。
`limit`	`number`	Optional	单页返回的最大条数。

Returns

ChannelListResult { channels: Channel[], next_cursor? }

Example

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

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

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

Returns

EventTypesResult { types: string[] }

Example

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

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

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

Parameters

Name	Type	Required	Description
`messages`	`Array<{ channel: string; event: string; data: unknown }>`	Required	要发布的消息列表，每条含 channel、event 和 data。
`idempotency_key`	`string`	Optional	幂等键，用于安全重试，避免重复发布。

Returns

PublishBatchResult { published }

Example

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

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

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

Parameters

Name	Type	Required	Description
`token_or_jti`	`string`	Required	完整令牌或其 jti 标识。
`idempotency_key`	`string`	Optional	幂等键，用于安全重试。

Returns

TokenRevokeResult { revoked }

Example

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

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

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

Parameters

Name	Type	Required	Description
`client_id`	`string`	Required	要断开连接的客户端身份标识。
`channel`	`string`	Optional	将断开限定到此频道；省略则全部断开。
`idempotency_key`	`string`	Optional	幂等键，用于安全重试。

Returns

UserDisconnectResult { disconnected }

Example

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

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": "..."}'

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`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.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

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

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"