Protoface

https://docs.protoface.com
Admin
Protoface is a generative media inference platform that provides a unified API for running frontier...
Tokens:86,057
Snippets:509
Trust Score:7.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install livekit-plugins-protoface

Source: https://docs.protoface.com/guides/livekit-agents

Install the plugin with pip.

```bash
pip install livekit-plugins-protoface

```

--------------------------------

### Install dependencies

Source: https://docs.protoface.com/quickstart

Creates a virtual environment and installs the required Python packages: livekit-plugins-protoface, livekit-plugins-google, and python-dotenv.

```bash
python -m venv .venv
source .venv/bin/activate
pip install livekit-plugins-protoface livekit-plugins-google python-dotenv

```

--------------------------------

### Agent install instruction

Source: https://docs.protoface.com/reference/mcp

Natural-language instruction to paste into an agent to install the Protoface MCP server. The agent should register it as 'protoface' at user scope and verify with list_models.

```text
Install the Protoface MCP server. It is a stdio server: the command is
`uvx protoface-mcp` and it needs the environment variable PROTOFACE_API_KEY,
which is already set in my shell. Register it under the name "protoface"
at user scope, then call its list_models tool to confirm it works.

```

--------------------------------

### Install pipecat-protoface

Source: https://docs.protoface.com/guides/pipecat

Add the pipecat-protoface package to your project. Install Pipecat extras for your transport, STT, LLM, TTS, or realtime model separately.

```bash
uv add pipecat-protoface

```

--------------------------------

### List billing plans with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/billing/list-billing-plans

Retrieve the list of billing plans from the Protoface API. The cURL command sends a GET request to the /v1/billing/plans endpoint, the Python example uses the requests library, and the JavaScript example uses fetch. All three examples target the same endpoint and are presented as interchangeable language options.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/billing/plans
```

```python
import requests

url = "https://api.protoface.com/v1/billing/plans"

response = requests.get(url)

print(response.text)
```

```javascript
const options = {method: 'GET'};

fetch('https://api.protoface.com/v1/billing/plans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Basic usage: create and start AvatarSession

Source: https://docs.protoface.com/guides/livekit-agents

Create an AvatarSession and start it before session.start(...). The plugin routes agent audio through a LiveKit DataStream to the avatar participant.

```python
from livekit.plugins import protoface

avatar = protoface.AvatarSession(avatar_id="av_stock_001")
await avatar.start(session, room=ctx.room)

await session.start(
    agent=agent,
    room=ctx.room,
)

```

--------------------------------

### Example run result JSON

Source: https://docs.protoface.com/guides/runs

Example response from the retrieve result endpoint. Shows the structure of a completed run, including outputs, credits, and error fields.

```json
{
  "id": "run_...",
  "object": "run",
  "model": "minimax/minimax-h3",
  "model_revision": "2026-08-20",
  "operation": "video.general",
  "status": "completed",
  "progress": 100,
  "video": {
    "url": "https://...",
    "content_type": "video/mp4",
    "file_name": "output.mp4",
    "file_size": 3919397
  },
  "image": null,
  "audio": null,
  "outputs": [
    {
      "role": "output",
      "modality": "video",
      "type": "asset",
      "asset_id": "asset_...",
      "file": {
        "url": "https://...",
        "content_type": "video/mp4",
        "file_name": "output.mp4",
        "file_size": 3919397
      },
      "text": null,
      "data": null
    }
  ],
  "credits": { "pricing_version": "model-2026-08-15", "reserved": 29, "charged": 29 },
  "error": null,
  "metadata": {},
  "external_id": null,
  "created_at": "2026-09-01T05:13:51.540770Z",
  "started_at": "2026-09-01T05:16:40.595801Z",
  "completed_at": "2026-09-01T05:26:02.667683Z"
}

```

--------------------------------

### LiveKit Transport Configuration Example

Source: https://docs.protoface.com/api-reference/sessions/retrieve-a-session

Example JSON object for the transport field, showing a LiveKit transport configuration with a data stream audio source, room name, type, and WebSocket URL.

```json
{
  "audio_source": "data_stream",
  "room_name": "demo-room",
  "type": "livekit",
  "url": "wss://my-app.livekit.cloud"
}
```

--------------------------------

### Start video from image with MiniMax H3

Source: https://docs.protoface.com/guides/image-to-video

Use this curl command to start a video generation run with MiniMax H3, passing a still image via the `first_frame` field. The image can be a public URL, data URI, or `asset_...` ID. The result is available on `video.url` when the run completes.

```bash
curl -X POST https://api.protoface.com/v1/run/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The sailboat holds course as morning light fills the bay.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9",
    "first_frame": "https://example.com/sailboat.png"
  }'
```

--------------------------------

### Generate video with MiniMax H3 via curl and fetch result

Source: https://docs.protoface.com/

Starts a video generation with the MiniMax H3 model and shows the JSON response containing the run ID and video file details. The request returns a run ID immediately; use GET /v1/runs/{id} to fetch the file once the run finishes.

```bash
curl -X POST https://api.protoface.com/v1/run/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A wide shot of a sailboat crossing a quiet bay at sunrise.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

```

```json
{
  "id": "run_...",
  "status": "completed",
  "video": {
    "url": "https://...",
    "content_type": "video/mp4",
    "file_name": "output.mp4"
  }
}

```

--------------------------------

### Use an avatar with LiveKit plugin

Source: https://docs.protoface.com/guides/avatars

Starts an avatar session using the LiveKit plugin. The avatar starts before the agent session; once running, `avatar.session_id` holds the Protoface `sess_...` ID. End it with `await avatar.aclose()` or `POST /v1/sessions/{id}/end`.

```python
from livekit.plugins import protoface

avatar = protoface.AvatarSession(avatar_id="av_stock_001")
```

--------------------------------

### Example response for creating a Pipecat avatar media session

Source: https://docs.protoface.com/api-reference/pipecat/create-a-pipecat-avatar-media-session

Example response body for a successful Pipecat avatar media session creation. Shows the session object with fields like avatar_id, transport details, and usage metrics.

```json
{
  "avatar_id": "av_stock_001",
  "billing_surface": "api",
  "created_at": "2026-05-25T19:00:00.123Z",
  "first_frame_at": "2026-05-25T19:00:02.001Z",
  "id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR",
  "idle_timeout_seconds": 30,
  "max_duration_seconds": 600,
  "metadata": { "customer_session_id": "abc123" },
  "object": "session",
  "quality": "standard",
  "started_at": "2026-05-25T19:00:01.456Z",
  "status": "running",
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud"
  },
  "usage": { "billable_seconds": 12, "frames": 300 }
}
```

--------------------------------

### Get quota limits with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/billing/get-quota-limits

Send a GET request to the quota endpoint with a Bearer token. The cURL, Python, and JavaScript examples are equivalent and return the quota details.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/billing/quota \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.protoface.com/v1/billing/quota"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.protoface.com/v1/billing/quota', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### 200 response for GET /v1/status

Source: https://docs.protoface.com/api-reference/platform/platform-status-roll-up

Example successful response from the status endpoint. The status field can be 'operational', 'degraded', or 'outage'.

```json
{
  "components": [
    {
      "name": "<string>",
      "status": "operational"
    }
  ],
  "status": "operational",
  "updated_at": "2023-11-07T05:31:56Z"
}
```

--------------------------------

### Retrieve a run with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/runs/retrieve-a-run

Retrieve a run by its ID using the GET /v1/runs/{run_id} endpoint. The cURL command uses the Authorization header with a Bearer token; the Python example uses the requests library; the JavaScript example uses fetch. Replace {run_id} with the actual run ID and <token> with your API token.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/runs/{run_id} \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.protoface.com/v1/runs/{run_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.protoface.com/v1/runs/{run_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Run the agent

Source: https://docs.protoface.com/quickstart

Starts the agent server. After running, connect to the same LiveKit room via Agents Playground to talk to the avatar.

```bash
python agent.py start

```

--------------------------------

### GET /v1/sessions/{id}

Source: https://docs.protoface.com/guides/livekit-agents

Retrieves information about a Protoface session. The session moves through `queued`, `starting`, and `running`. `first_frame_at` is set when the first frame reaches the room, and a `protoface-avatar-agent` participant publishes audio and video into it.

```APIDOC
## [GET] /v1/sessions/{id}

### Description
Retrieves information about a Protoface session. The session moves through `queued`, `starting`, and `running`. `first_frame_at` is set when the first frame reaches the room, and a `protoface-avatar-agent` participant publishes audio and video into it.

### Method
GET

### Endpoint
/v1/sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID (e.g., `sess_...`).

### Request Example
```
curl https://api.protoface.com/v1/sessions/sess_... \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

### Response
#### Success Response (200)
- **session_id** (string) - The session ID.
- **status** (string) - The session status (`queued`, `starting`, `running`).
- **first_frame_at** (timestamp) - When the first frame reaches the room.
- **usage.billable_seconds** (number) - Billing usage, settled after the fact.

#### Response Example
No explicit response example is provided in the source.

```

--------------------------------

### Install with Codex

Source: https://docs.protoface.com/reference/mcp

Registers the Protoface MCP server with Codex, passing the API key as an environment variable.

```bash
codex mcp add protoface --env PROTOFACE_API_KEY="$PROTOFACE_API_KEY" -- uvx protoface-mcp

```

--------------------------------

### Retrieve an avatar with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/avatars/retrieve-an-avatar

Sends a GET request to the retrieve avatar endpoint with a Bearer token. The Python and JavaScript examples print or log the response, while cURL outputs the raw response.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/avatars/{avatar_id} \
  --header 'Authorization: Bearer <token>'

```

```python
import requests

url = "https://api.protoface.com/v1/avatars/{avatar_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.protoface.com/v1/avatars/{avatar_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

```

--------------------------------

### Create agent.py with Protoface avatar

Source: https://docs.protoface.com/quickstart

Defines the agent entrypoint that creates an AgentSession with a Gemini Live realtime model, starts a Protoface AvatarSession, and begins the session with the avatar publishing audio. The room_options disable audio output so Protoface can publish the assistant audio.

```python
import os

from dotenv import load_dotenv
from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    TurnHandlingOptions,
    cli,
    room_io,
)
from livekit.plugins import google, protoface

load_dotenv()

server = AgentServer()
AGENT_INSTRUCTIONS = (
    "You are a friendly AI avatar. "
    "Keep responses natural, concise, and conversational."
)


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        llm=google.realtime.RealtimeModel(
            model=os.getenv("GEMINI_MODEL", "gemini-3.1-flash-live-preview"),
            voice=os.getenv("GEMINI_VOICE", "Charon"),
        ),
        turn_handling=TurnHandlingOptions(
            interruption={"resume_false_interruption": False},
        ),
    )

    avatar = protoface.AvatarSession(
        avatar_id=os.getenv("PROTOFACE_AVATAR_ID", protoface.DEFAULT_STOCK_AVATAR_ID),
    )
    await avatar.start(session, room=ctx.room)

    await session.start(
        agent=Agent(instructions=AGENT_INSTRUCTIONS),
        room=ctx.room,
        # Let Protoface publish the assistant audio.
        room_options=room_io.RoomOptions(audio_output=False),
    )


if __name__ == "__main__":
    cli.run_app(server)

```

--------------------------------

### Retrieve a model with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/models/retrieve-a-model

Retrieve a model by its ID using the Protoface API. The endpoint is GET /v1/models/{model_id} and requires an Authorization header with a Bearer token. The cURL, Python (requests), and JavaScript (fetch) examples are equivalent ways to call the same endpoint.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/models/{model_id} \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.protoface.com/v1/models/{model_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.protoface.com/v1/models/{model_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Use an asset ID in a run (MiniMax H3)

Source: https://docs.protoface.com/guides/assets

Starts a generation run that uses an uploaded asset as the `first_frame` input. The field name for the asset ID varies by model; for MiniMax H3 it is `first_frame`. Use `GET /v1/models/{model_id}` to list field names for other models.

```bash
curl -X POST https://api.protoface.com/v1/run/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The ceramic lamp turns slowly under a single studio light.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9",
    "first_frame": "asset_..."
  }'

```

--------------------------------

### Generate a video with MiniMax H3 via /v1/run/{model_id}

Source: https://docs.protoface.com/guides/model-inference

Submits a video generation prompt to /v1/run/minimax/minimax-h3 using curl, httpx, or fetch. The MiniMax H3 model takes a length in seconds, a quality tier, and an aspect ratio, and returns video with sound. The response is a 202 with a run ID; generation continues in the background.

```bash
curl -X POST https://api.protoface.com/v1/run/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-video-001" \
  -d '{
    "prompt": "A wide shot of a sailboat crossing a quiet bay at sunrise.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

```

```python
import os

import httpx

created = httpx.post(
    "https://api.protoface.com/v1/run/minimax/minimax-h3",
    headers={
        "Authorization": f"Bearer {os.environ['PROTOFACE_API_KEY']}",
        "Idempotency-Key": "first-video-001",
    },
    json={
        "prompt": "A wide shot of a sailboat crossing a quiet bay at sunrise.",
        "duration_seconds": 8,
        "quality": "768p",
        "aspect_ratio": "16:9",
    },
    timeout=60.0,
)
created.raise_for_status()
run_id = created.json()["id"]

```

```javascript
const created = await fetch(
  "https://api.protoface.com/v1/run/minimax/minimax-h3",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PROTOFACE_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "first-video-001",
    },
    body: JSON.stringify({
      prompt: "A wide shot of a sailboat crossing a quiet bay at sunrise.",
      duration_seconds: 8,
      quality: "768p",
      aspect_ratio: "16:9",
    }),
  },
);

const { id: runId } = await created.json();

```

--------------------------------

### Verification prompt

Source: https://docs.protoface.com/reference/mcp

Example prompt to ask the agent after restarting it, to verify the MCP server is working.

```text
List the Protoface models and my credit balance.

```

--------------------------------

### GET /v1/runs/{run_id}/status

Source: https://docs.protoface.com/api-reference/runs/poll-run-status

Documentation for polling the status of a run using the GET /v1/runs/{run_id}/status endpoint.

```APIDOC
## GET /v1/runs/{run_id}/status

### Description
Polls the status of a run by its unique identifier. Returns the current progress, queue position, and status of the run.

### Method
GET

### Endpoint
https://api.protoface.com/v1/runs/{run_id}/status

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.

#### Headers
- **Authorization** (string) - Required - Live API key minted in the dashboard. Pass as `Authorization: Bearer sk_live_…`. Keys are scoped to a single environment (staging / prod).

### Request Example
```
curl --request GET \
  --url https://api.protoface.com/v1/runs/{run_id}/status \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **error** (RunErrorView | null) - required - Error details if any.
- **id** (string) - required - The run identifier.
- **progress** (integer) - required - Progress of the run.
- **queue_position** (integer | null) - required - Position in the queue.
- **status** (string) - required - Current status of the run.
- **object** (string) - default: `run.status` - Allowed value: `"run.status"`.

#### Response Example
```
{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "id": "<string>",
  "progress": 123,
  "queue_position": 123,
  "status": "<string>",
  "object": "run.status"
}
```

### Error Handling
- **402** - Payment Required
- **403** - Forbidden
- **409** - Conflict
- **422** - Unprocessable Entity
- **429** - Too Many Requests

Error responses include an error object with code, message, param, request_id, and type fields.
```

--------------------------------

### Create ProtofaceVideoService with API key and avatar ID

Source: https://docs.protoface.com/guides/pipecat

Create the Protoface video service with an API key and avatar ID. The API key is read from the PROTOFACE_API_KEY environment variable, and the avatar ID from PROTOFACE_AVATAR_ID.

```python
import os

from pipecat_protoface import ProtofaceVideoService

protoface = ProtofaceVideoService(
    api_key=os.environ["PROTOFACE_API_KEY"],
    avatar_id=os.environ["PROTOFACE_AVATAR_ID"],
)

```

--------------------------------

### Create a session with cURL, Python, and JavaScript

Source: https://docs.protoface.com/api-reference/sessions/create-a-session

Create a session by POSTing to /v1/sessions with an avatar_id and a livekit transport. The request returns immediately with status queued; poll GET /v1/sessions/{id} or wait for the session.first_frame webhook. Requires a Bearer token and Content-Type application/json.

```bash
curl --request POST \
  --url https://api.protoface.com/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "avatar_id": "av_stock_001",
  "transport": {
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud",
    "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
'
```

```python
import requests

url = "https://api.protoface.com/v1/sessions"

payload = {
    "avatar_id": "av_stock_001",
    "transport": {
        "room_name": "demo-room",
        "type": "livekit",
        "url": "wss://my-app.livekit.cloud",
        "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

```javascript
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    avatar_id: 'av_stock_001',
    transport: {
      room_name: 'demo-room',
      type: 'livekit',
      url: 'wss://my-app.livekit.cloud',
      worker_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  })
};

fetch('https://api.protoface.com/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### cURL request to GET /v1/status

Source: https://docs.protoface.com/api-reference/platform/platform-status-roll-up

Use this cURL command to fetch the platform status roll-up. It sends a GET request to https://api.protoface.com/v1/status.

```bash
curl --request GET \
  --url https://api.protoface.com/v1/status
```

--------------------------------

### Full run sequence with curl and jq

Source: https://docs.protoface.com/guides/model-inference

Complete sequence using curl and jq: create a run, poll status until terminal, then fetch the video URL. Uses the Idempotency-Key header for the creation request.

```bash
RUN_ID=$(curl -s -X POST https://api.protoface.com/v1/run/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-video-001" \
  -d '{
    "prompt": "A wide shot of a sailboat crossing a quiet bay at sunrise.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }' | jq -r .id)

while true; do
  STATUS=$(curl -s "https://api.protoface.com/v1/runs/$RUN_ID/status" \
    -H "Authorization: Bearer $PROTOFACE_API_KEY" | jq -r .status)
  case "$STATUS" in
    completed|failed|canceled) break ;;
  esac
  sleep 1
done

curl -s "https://api.protoface.com/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  | jq -r '.video.url // .error.message'

```

--------------------------------

### Create a session with Python requests

Source: https://docs.protoface.com/api-reference/sessions/create-a-session

Creates a session using the requests library. Sends a POST request with the same payload and headers as the cURL example, then prints the response.

```python
import requests

url = "https://api.protoface.com/v1/sessions"

payload = {
    "avatar_id": "av_stock_001",
    "transport": {
        "room_name": "demo-room",
        "type": "livekit",
        "url": "wss://my-app.livekit.cloud",
        "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### List avatars with GET /v1/avatars

Source: https://docs.protoface.com/guides/avatars

Lists all avatars for the authenticated account. Requires a valid `$PROTOFACE_API_KEY`.

```bash
curl https://api.protoface.com/v1/avatars \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

--------------------------------

### Authorization header with Bearer token

Source: https://docs.protoface.com/guides/authentication

Required header for all /v1 endpoints except GET /v1/status and GET /v1/billing/plans. Keys are created in the dashboard and belong to either staging or production.

```http
Authorization: Bearer sk_live_...
```

--------------------------------

### Successful usage summary response

Source: https://docs.protoface.com/api-reference/usage/get-usage-summary

Example of a successful response with usage metrics such as billable_seconds, credits_charged, and daily breakdowns.

```json
{
  "billable_seconds": 14280,
  "by_billing_surface": {
    "api": 180,
    "playground": 58
  },
  "by_quality": {
    "pro": 2280,
    "standard": 12000
  },
  "by_speech_billing_mode": {
    "customer_managed": 180,
    "platform_managed": 58
  },
  "credits_charged": 238,
  "daily_credits_by_billing_surface": {
    "2026-05-24": {
      "api": 180
    },
    "2026-05-25": {
      "playground": 58
    }
  },
  "period_end": "2026-05-25T19:00:00Z",
  "period_start": "2026-05-01T00:00:00Z",
  "sessions": 42
}
```

--------------------------------

### GET /v1/assets

Source: https://docs.protoface.com/llms.txt

List assets.

```APIDOC
## GET /v1/assets

### Description
List assets.

### Method
GET

### Endpoint
/v1/assets

### Parameters
None documented.

### Response
#### Success Response (200)
List of assets.

#### Response Example
```json
{
  "data": [
    {
      "id": "asset-id",
      "object": "asset"
    }
  ]
}
```
```

--------------------------------

### POST /v1/run/minimax/minimax-h3

Source: https://docs.protoface.com/guides/image-to-video

Documentation for creating a video from a still image using the MiniMax H3 model.

```APIDOC
## POST /v1/run/minimax/minimax-h3

### Description
Creates a video generation run from a still image using the MiniMax H3 model. The image is supplied in the `first_frame` field as a public URL, data URI, or asset ID.

### Method
POST

### Endpoint
https://api.protoface.com/v1/run/minimax/minimax-h3

### Parameters
#### Request Body
- **prompt** (string) - Required - Text prompt describing the video content.
- **duration_seconds** (integer) - Required - Duration of the video in seconds.
- **quality** (string) - Required - Video quality, e.g., "768p".
- **aspect_ratio** (string) - Required - Aspect ratio, e.g., "16:9".
- **first_frame** (string) - Required - Public URL, data URI, or asset ID of the opening frame image.

### Request Example
```json
{
  "prompt": "The sailboat holds course as morning light fills the bay.",
  "duration_seconds": 8,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "first_frame": "https://example.com/sailboat.png"
}
```

### Response
#### Success Response (200)
- **video.url** (string) - URL of the generated video clip.

#### Response Example
```json
{
  "video": {
    "url": "https://example.com/video.mp4"
  }
}
```

### Error Handling
- **run.input_role_dependency** - Returned when `last_frame` is sent without `first_frame`.
- **run.input_role_conflict** - Returned when `first_frame` or `last_frame` is combined with `reference`, `reference_video`, or `audio`.
```

--------------------------------

### GET /v1/models

Source: https://docs.protoface.com/llms.txt

List available models.

```APIDOC
## GET /v1/models

### Description
List available models.

### Method
GET

### Endpoint
/v1/models

### Parameters
None documented.

### Response
#### Success Response (200)
List of models.

#### Response Example
```json
{
  "data": [
    {
      "id": "model-id",
      "object": "model"
    }
  ]
}
```
```

--------------------------------

### Configuration: pass options directly

Source: https://docs.protoface.com/guides/livekit-agents

Pass configuration options directly to AvatarSession instead of using environment variables.

```python
avatar = protoface.AvatarSession(
    avatar_id="av_stock_001",
    api_key="sk_live_...",
)

await avatar.start(
    session,
    room=ctx.room,
    livekit_url="wss://your-project.livekit.cloud",
    livekit_api_key="...",
    livekit_api_secret="...",
)

```
Tokens:
Raw