> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apob.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI livestream channels with MCP

> Let your agent create APOB AI livestream channels, add scenes, and vote using MCP, with explicit credit and playback handling.

Use APOB's Live tools to turn a creative brief into a channel and let an agent
propose what happens next. Start with the
[livestream quickstart](https://developers.apob.ai/guides/create-livestream-channel.md) for the complete workflow.

Connect with [OAuth](https://developers.apob.ai/mcp/authentication.md), initialize using
[Streamable HTTP](https://developers.apob.ai/mcp/protocol.md), and call `tools/list` to inspect the tools
exposed to the current account and connection. Use the MCP access token, not a
GraphQL API key, on `APOB_MCP_URL`.

> [!NOTE]
>
> **Channel** is the product term. MCP keeps the tool name `create_live_room`
> and argument names such as `roomId` and `sourceLiveRoomId`. A channel ID is
> the value to supply for these identifiers; do not rename the arguments.

## create\_live\_room

Creates a new channel and prepays its initial generation using APOB credits.

| Argument | Required | Contract |
| - | - | - |
| `initialPrompt` | Yes | Nonblank description of the initial scene. |
| `initialLength` | Yes | Integer milliseconds, `15000–15000000`; rounded up to a whole second. |
| `resolution` | Yes | `P480` or `P768`. |
| `isPublic` | Yes | Explicit boolean; public channels are discoverable, private channels are owner-only. |
| `audienceSceneCreationEnabled` | No | Boolean, defaults to `true`; choose explicitly for agent-created channels. |
| `sourceMediaId` | No | Accessible image/video media ID as a positive decimal string, at most `9223372036854775807`. |
| `sourceLiveRoomId` | No | Accessible channel to use as a continuation source. |
| `uploadedImage` | No | Object with only `url` from your own `import_file` or `complete_file_upload`. |
| `uploadedVideo` | No | Object with only `url` from your own `import_file` or `complete_file_upload`. |

Supply at most one source argument. Omit all sources for text-only creation.
Canonical uploaded URLs belong to the connected account; external URLs,
`previewUrl`, signed preview links, and another account's uploads are rejected.
Use the [upload/import workflow](https://developers.apob.ai/mcp/uploads-and-live.md) first for local or remote
files. MCP uploaded objects do not take width, height, or other properties.

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 40,
  "method": "tools/call",
  "params": {
    "name": "create_live_room",
    "arguments": {
      "initialPrompt": "A tiny robot explores a greenhouse on the moon.",
      "initialLength": 15000,
      "resolution": "P480",
      "isPublic": false,
      "audienceSceneCreationEnabled": false
    }
  }
}
```

The successful `result.structuredContent` contains:

| Field | Meaning |
| - | - |
| `id`, `title` | New channel identity and title. Save `id`. |
| `status` | `LIVE` or `ENDED`; active channel state, not player readiness. |
| `initialPrompt`, `initialLength` | Accepted prompt and normalized initial duration in milliseconds. |
| `resolution`, `isPublic`, `audienceSceneCreationEnabled` | Accepted channel settings. |
| `cloudflareHlsPlaybackUrl` | Nullable live HLS URL. Startup is asynchronous even when a URL is present. |

An image source provides a starting visual. A video source becomes a ready first
scene; `initialLength` funds additional generated continuation. A source channel
uses its latest usable ready scene when available, otherwise generation starts
from text. Source access and moderation requirements apply to every creation.

## create\_live\_scene

Creates a candidate scene in an accessible active channel. Non-owner requests also
require audience scene creation to be enabled.

| Argument | Required | Contract |
| - | - | - |
| `roomId` | Yes | Nonblank channel ID. |
| `prompt` | Yes | Nonblank scene prompt. |
| `creditAmount` | Yes | Integer `0–2147483647`. Zero means no initial vote; positive values charge eligible credits. |

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 41,
  "method": "tools/call",
  "params": {
    "name": "create_live_scene",
    "arguments": {
      "roomId": "<CHANNEL_ID_FROM_RECEIPT>",
      "prompt": "The robot finds a glowing seed and plants it beside the window.",
      "creditAmount": 0
    }
  }
}
```

Returns `id`, `roomId`, `prompt`, `votedCreditAmount`, and `useFreeVote`.
`votedCreditAmount` is accumulated vote weight; `useFreeVote` says whether the
current account has already used its free vote on the scene.

An owner's positive request funding more than 15 seconds can create a batch of
5–15 second scenes, at most 1000; the tool returns only its first scene. Read the
channel's scene lists through GraphQL to see the whole batch. Candidate creation
does not by itself prove selection, generation, or playback.

## vote\_live\_scene

Votes on an eligible scene in the specified accessible channel.

| Argument | Required | Contract |
| - | - | - |
| `roomId` | Yes | Nonblank channel ID. |
| `sceneId` | Yes | Nonblank ID of a scene in that channel. |
| `creditAmount` | Yes | Integer `0–2147483647`. Zero uses one free vote worth 100 weight, once per account per scene; positive values charge that many eligible credits and add equal weight. |

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "vote_live_scene",
    "arguments": {
      "roomId": "<CHANNEL_ID_FROM_RECEIPT>",
      "sceneId": "<SCENE_ID_FROM_RECEIPT>",
      "creditAmount": 0
    }
  }
}
```

Returns `voteId`, `scene` (the fields returned by scene creation),
`creditAmount` (credits charged for this vote), and `refunded` (boolean).
The free vote is separate from creating a zero-credit candidate. Each paid vote
can charge again; repeated free votes are rejected.

## Observe and manage the channel

The registered MCP Live surface consists of the three tools above. It has no
channel read, list, stop, reopen, or playback subscription tool. Use the
[GraphQL Live API](https://developers.apob.ai/api-reference/live-streaming.md) with separate API credentials,
or hand the channel ID to the user in [APOB](https://app.apob.ai).

* Observe `liveRoom(id: ...)` for channel state, HLS, scene progression, and replays.
* Use `listPersonalLiveRooms` to reconcile an uncertain creation in the same account.
* Owner controls are `stopLiveRoom`, `reopenLiveRoom`, and
  `setLiveRoomAudienceSceneCreationEnabled`.
* Give the exact returned HLS URL to a player; verify its playback events.

`get_generation_result` accepts generation task IDs and does not monitor channels.
Reopening through GraphQL creates a new channel and new prepaid work.

## Credits and error handling

Inspect JSON-RPC errors, `result.isError`, and the returned fields. HTTP 200 alone
does not prove success. Live errors include inaccessible sources or channels,
moderation rejection, ended channels, disabled audience proposals, insufficient
eligible credits, an already-used free vote, and concurrent-state conflicts.

> [!WARNING]
>
> Live creation, scene creation, and voting are non-idempotent. A JSON-RPC ID is
> only for response correlation. Save receipts and reconcile an uncertain write
> before considering another call. Do not use an agent loop that creates channels
> until a playable URL appears.

Channel creation prepays generation; positive scene/vote amounts spend eligible
credits. Account settings and connection policy determine whether automatic
reload can apply. Review [credits and billing](https://developers.apob.ai/credits-and-billing.md) before
authorizing work. No public Live price-quote tool is registered; do not treat
`initialLength`, vote weight, or a creation receipt as an exact price quote or
promise of a refund.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.