> ## 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.

# Create an AI livestream channel

> Build an AI livestream channel with the APOB API or your MCP agent: create a channel, add scenes, enable audience participation, and retrieve HLS playback.

Build an AI livestream around a world, character, or story. APOB generates scenes
and streams them in a channel, with optional audience scene proposals and voting.
Start with a text prompt, an accessible image or video, or an existing channel.

> [card] [Build with the API](https://developers.apob.ai/api-reference/live-streaming.md)
>
> Create channels, read playback and scenes, control audience participation, stop,
> and reopen through GraphQL.

> [card] [Create with your agent](https://developers.apob.ai/mcp/live-streaming.md)
>
> Use MCP tools to create a channel, propose scenes, and vote from an authorized client.

## Choose your integration

| You want to… | Use |
| - | - |
| Let an agent create a channel from a brief | MCP `create_live_room` |
| Integrate channel creation and a player into your application | GraphQL `createLiveRoom` and `liveRoom` |
| Add an audience-driven next scene | MCP `create_live_scene` / `vote_live_scene`, or their GraphQL equivalents |
| Read channel history, inspect readiness, stop, or reopen | GraphQL Live API, or the APOB application |

Channels stream generated video scenes over HLS. Generation and playback start
asynchronously. Plan your interface around a preparing state followed by actual
player readiness; there is no fixed startup-time guarantee.

## Before you start

* Sign in to the APOB account that will own the channel and review its eligible
  credits and automatic reload settings in [credits and billing](https://developers.apob.ai/credits-and-billing.md).
* For the API, obtain an APOB API key and the integration's GraphQL URL. Examples
  use `APOB_GRAPHQL_URL` and `APOB_API_KEY`.
* For MCP, connect the integration's `APOB_MCP_URL` using
  [OAuth](https://developers.apob.ai/mcp/authentication.md), initialize, and discover the current tools.
* Choose the prompt, initial generated duration, resolution, visibility, and
  audience policy explicitly. `15000` milliseconds means 15 seconds.

For production, use these endpoint variables:

```bash theme={"system"}
export APOB_GRAPHQL_URL='https://backend.apob.ai/graphql'
export APOB_MCP_URL='https://backend.apob.ai/mcp'
```

An MCP OAuth token and a GraphQL API key are separate credentials. An agent that
only has MCP access must hand channel observation or owner controls to the user or
an independently authorized API integration.

## 1. Create the channel once

This example requests a private channel, 15 seconds of initial generation, and no
audience scene creation. Channel creation prepays generation with credits.

> [tab] GraphQL API
>
> Save this request as `create-channel.json`:
>
> ```json theme={"system"}
> {
>   "operationName": "CreateChannel",
>   "query": "mutation CreateChannel($input: CreateLiveRoomInput!) { createLiveRoom(input: $input) { id title status isPublic audienceSceneCreationEnabled cloudflareHlsPlaybackUrl } }",
>   "variables": {
>     "input": {
>       "initialPrompt": "A quiet floating garden at sunrise. The camera glides past glass flowers toward a small observatory.",
>       "initialLength": 15000,
>       "resolution": "P480",
>       "isPublic": false,
>       "audienceSceneCreationEnabled": false
>     }
>   }
> }
> ```
>
> Send it from a trusted server or local environment:
>
> ```bash theme={"system"}
> curl --request POST "$APOB_GRAPHQL_URL" \
>   --header "Authorization: Bearer $APOB_API_KEY" \
>   --header 'Content-Type: application/json' \
>   --data-binary @create-channel.json
> ```
>
> Check both `data` and `errors`, even on HTTP 200. Save the returned
> `data.createLiveRoom.id` before doing anything else. Keep your API key out of
> public browser code and logs.

> [tab] MCP agent
>
> After [initialization](https://developers.apob.ai/mcp/protocol.md#initialize), call:
>
> ```json theme={"system"}
> {
>   "jsonrpc": "2.0",
>   "id": 30,
>   "method": "tools/call",
>   "params": {
>     "name": "create_live_room",
>     "arguments": {
>       "initialPrompt": "A quiet floating garden at sunrise. The camera glides past glass flowers toward a small observatory.",
>       "initialLength": 15000,
>       "resolution": "P480",
>       "isPublic": false,
>       "audienceSceneCreationEnabled": false
>     }
>   }
> }
> ```
>
> Check the top-level JSON-RPC error and `result.isError`. Save the channel `id`
> from `result.structuredContent` on success. The same JSON is also returned
> in a text content entry. Follow the [Live MCP reference](https://developers.apob.ai/mcp/live-streaming.md)
> for source inputs and receipt fields.

> [!WARNING]
>
> Do not retry creation automatically after a timeout or an unclear response.
> Every successful creation makes another channel and can spend credits again.
> Inspect the same account's channel history before considering a new submission.

## 2. Observe startup and play the stream

Read the saved channel ID through GraphQL, using an API key for the channel owner when
the channel is private. Replace the synthetic ID with the real receipt:

```graphql theme={"system"}
query ObserveChannel($id: ID!) {
  liveRoom(id: $id) {
    id
    status
    cloudflareHlsPlaybackUrl
    generatedDurationMs
    scenes {
      isStreamEnded
      current { id videoUrl generatedTime streamStartedTime }
      queued { id }
    }
  }
}
```

```json theme={"system"}
{ "id": "<CHANNEL_ID_FROM_RECEIPT>" }
```

Use spaced reads with a bounded wait and a visible preparing state. Retry a
failed read against the same channel ID. `status: LIVE` means the channel is active;
even a non-null playback URL does not prove media is ready. Give the returned
`cloudflareHlsPlaybackUrl` unchanged to an HLS-capable player and handle its
loading, playback, and error events. Confirm playback through the player.

`generatedTime` describes successful scene generation. `streamStartedTime`
records a runtime scene-start callback and can still be null for `current`.
`scenes.isStreamEnded` describes an exhausted queue with repeated playback;
it is separate from `status: ENDED`.

MCP currently has no channel-status tool. Do not pass a channel ID to
`get_generation_result`; that tool follows generation tasks, not Live channels.

## 3. Add the next scene or invite participation

Create a scene with `createLiveScene` or `create_live_scene`, passing the channel
ID, prompt, and `creditAmount`. Then use `voteLiveScene` or `vote_live_scene`
with the returned scene ID.

* Creating a scene with `creditAmount: 0` makes a candidate with no initial vote.
* Voting with `creditAmount: 0` uses the account's one free vote per scene and
  adds 100 vote weight.
* Positive values charge eligible credits. Vote weight is not a receipt of total
  credits spent. A candidate or a vote does not guarantee generation or airtime.

Use `isPublic: true` when creating a channel intended for public discovery. Set
`audienceSceneCreationEnabled: true` to permit eligible viewers to propose scenes;
it defaults to true when omitted. The owner can change this policy through
GraphQL. Public visibility does not grant owner controls. Private channels are
readable only by their owner through the channel API.

## 4. End, replay, or continue

The owner can call `stopLiveRoom(id: ...)` to end the channel. Read the same channel
later for `cloudflareReplayHlsPlaybackUrl` or `replayVideoUrl`. The assembled
MP4 `replayVideoUrl` is nullable while postprocessing completes and is signed;
read the channel again when a fresh URL is needed.

To continue an owned ended channel, use `reopenLiveRoom`. Reopening creates a
**new channel ID** and prepays new generation. Save the new receipt. See the
[lifecycle examples](https://developers.apob.ai/api-reference/live-streaming.md#owner-controls).

## Give an agent a complete brief

```text theme={"system"}
Create one APOB AI livestream channel about a floating garden at sunrise.
Use 15 seconds of initial generation at P480. Make it private and disable
audience scene creation. Use my existing eligible credits; do not purchase
anything or change billing settings. Report the channel ID and playback URL
if returned. If the outcome is uncertain, stop and help me inspect channel
history instead of creating another channel. Do not claim playback has started
until it has been observed in a player.
```

The connected client must support APOB's MCP transport and OAuth flow. Available
credits, moderation, source access, and channel lifecycle rules still apply. For
failures, follow [Live troubleshooting](https://developers.apob.ai/troubleshooting.md#the-channel-is-live-but-playback-has-not-started).


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