API Tokens

Want to use the OpenClaw API?

Programmatic video generation is available on our paid plans. Choose a plan to get your API key and start automating your video workflow today.

View Pricing

API Documentation

Token-authenticated JSON endpoints for bots and server-to-server clients.

Authentication

All /api/* endpoints require an API token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Base URL

https://api.lovelybots.com/api

Uses PUBLIC_API_BASE_URL when set, then PUBLIC_ACTIVE_STORAGE_BASE_URL, then PUBLIC_APP_BASE_URL, then APP_PROTOCOL + APP_HOST.

Use https://api.lovelybots.com/api for bot and server-to-server calls. Keep dashboard/login flows on https://lovelybots.com.

Endpoint Reference

POST /api/create accepts a single image field (file upload, URL, or base64).

Method	Path	Description
POST	/api/create	Primary create endpoint for video generation.
POST	/api/videos	Create alias. Same request/response schema as `/api/create`.
GET	/api/credits	Returns remaining video credits and usage totals.
GET	/api/voices	List available voices with IDs for `voice_id`.
GET	/api/videos	Lists videos for the authenticated user.
GET	/api/videos/:id	Returns one video object.
GET	/api/videos/:id/status	Poll-ready status payload for generation progress.

Common Error Response

{
  "error": "Error message"
}

Typical statuses: 401 missing/invalid token, 403 IP blocked or quota/plan restriction, 404 video not found, 422 validation/input error, 503 API disabled.

`POST` /api/create

Create a video with script + one image input. The backend auto-detects whether it is an upload, URL, or base64.

Best output quality: use a clear front-facing portrait in 9:16 orientation (example: 1080x1920).

Input Schema

Field	Type	Required	Description
script	string	Yes	Script text for generation.
image	file or string (URL/base64)	Yes	Unified image input. Send multipart file upload, http/https URL string, or base64/data URL string. URL inputs must be publicly reachable (localhost/private-network URLs are blocked). For best quality, use a front-facing `9:16` portrait.
gender	string	No	Manual gender ("male", "female"). Overrides AI detection.
age	string	No	Manual age ("young_adult", "adult", "senior"). Overrides AI detection.
voice_id	integer	No	Voice to force. If omitted, a voice is auto-selected.
action_prompt	string	No	Presenter action/performance guidance (e.g. "Smiles warmly and waves").
camera_prompt	string	No	Camera/framing guidance (e.g. "Medium closeup, cinematic lighting").
subtitles	boolean	No	Enable subtitle generation.
public	boolean	No	Set to `false` to keep the video private. Defaults to `true` (visible on the public feed lovelybots.com/feed).

Output Schema (201 Created)

Field	Type	Description
id	integer	Video ID. Use to poll `GET /api/videos/:id`.
status	string	Initial status — always `queued` on creation.
credits_remaining	integer	Videos remaining in your plan this month.
share_url	string	Public shareable page for this video.

Request Example (Multipart Upload)

curl -X POST "https://api.lovelybots.com/api/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "script=Three launch hooks for this week" \
  -F "image=@/absolute/path/to/image_1080x1920.jpg" \
  -F "action_prompt=Confident delivery with hand gestures" \
  -F "camera_prompt=Medium close-up, slight push-in" \
  -F "subtitles=true" \
  -F "voice_id=12"

Request Example (JSON Base64)

curl -X POST "https://api.lovelybots.com/api/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Three launch hooks for this week",
    "voice_id": 12,
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "action_prompt": "Confident delivery with hand gestures",
    "camera_prompt": "Medium close-up, slight push-in"
  }'

Response Example (201)

{
  "id": 4321,
  "status": "queued",
  "credits_remaining": 12,
  "share_url": "https://lovelybots.com/videos/4321/share/abc123token"
}

`GET` /api/voices

Returns voices you can use in voice_id when calling POST /api/create. Filter by gender and age.

Query Parameters

Param	Values
gender	`male`, `female`
age	`young_adult`, `adult`, `mature`, `middle_aged`, `older`

Output Schema

Field	Type	Description
voices	array[object]	Available voice entries.
voices[].id	integer	Use as `voice_id` in create requests.
voices[].name	string	Voice display name.
voices[].gender	string	`male` or `female`.
voices[].age	string	`young_adult`, `adult`, `mature`, `middle_aged`, or `older`.

{
  "voices": [
    {
      "id": 12,
      "name": "Alloy (Female, Adult)",
      "gender": "female",
      "age": "adult"
    }
  ]
}

`GET` /api/credits

Returns current user credit balances and reset timing.

Output Schema

Field	Type	Description
credits.videos_remaining	integer	Remaining videos available now.
credits.videos_this_month	integer	Videos generated in current billing period.
credits.videos_created_all_time	integer	Lifetime videos generated.
credits.next_reset	datetime or null	Next credit reset time (ISO8601).

{
  "credits": {
    "videos_remaining": 9,
    "videos_this_month": 3,
    "videos_created_all_time": 42,
    "next_reset": "2026-03-01T00:00:00.000Z"
  }
}

`GET` /api/videos

List videos for the authenticated user.

Query Parameters

Parameter	Type	Description
status	string	Filter by one status: `pending`, `queued`, `processing`, `completed`, `failed`.
completed	string	If `true`, filters to completed videos.
failed	string	If `true`, filters to failed videos.
page	integer	Page number.
per_page	integer	Items per page. Default `12`.

Output Schema

Field	Type	Description
videos	array[Video]	Array of video objects (latest first).
pagination.current_page	integer	Current page number.
pagination.total_pages	integer	Total number of pages.
pagination.total_count	integer	Total matching videos.

{
  "videos": [ { "...": "Video object" } ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 40
  }
}

`GET` /api/videos/:id

Returns the polling-friendly summary used by the OpenClaw skill.

Field	Type	Description
id	integer	Video ID.
status	string	`queued`, `processing`, `completed`, or `failed`.
share_url	string	Public shareable page URL. Always present.
credits_remaining	integer	Videos remaining on your plan this month.
video_url	string or null	Playable URL. Present when `completed`.
error	string or null	Failure reason. Present when `failed`.

{
  "id": 4321,
  "status": "processing",
  "credits_remaining": 12,
  "share_url": "https://lovelybots.com/videos/4321/share/abc123token"
}

`GET` /api/videos/:id/status

Low-level provider status payload with progress and provider job metadata.

Field	Type	Description
id	integer	Video ID.
status	string	`pending`, `queued`, `processing`, `completed`, or `failed`.
job_id	string or null	Provider job identifier when available.
video_url	string or null	Playable URL. Present when `completed`.
thumbnail_url	string or null	Thumbnail URL when available.
progress	number, string, or null	Provider progress indicator.
error	string or null	Failure reason. Present when `failed`.
created_at	datetime	Creation timestamp (ISO8601).
completed_at	datetime or null	Completion timestamp.

{
  "id": 4321,
  "status": "processing",
  "job_id": "fal_abc123",
  "video_url": null,
  "thumbnail_url": null,
  "progress": 62,
  "error": null,
  "created_at": "2026-02-19T20:34:02.127Z",
  "completed_at": null
}

Video Object Schema

Field	Type	Description
id	integer	Video ID.
status	string	Current status.
video_url	string or null	Final playable video URL.
thumbnail_url	string or null	Thumbnail URL. Falls back to placeholder when not generated.
share_url	string	Public shareable page URL.
created_at	datetime	Creation timestamp (ISO8601).
completed_at	datetime or null	Completion timestamp.
image.id	integer or null	Source image record ID.
image.name	string or null	Source image display name.
image.image_url	string or null	Source image URL.
voice.id	integer or null	Voice ID.
voice.name	string or null	Voice display name.

Want to use the OpenClaw API?

API Documentation

Authentication

Base URL

Endpoint Reference

Common Error Response

POST /api/create

Input Schema

Output Schema (201 Created)

Request Example (Multipart Upload)

Request Example (JSON Base64)

Response Example (201)

GET /api/voices

Query Parameters

Output Schema

GET /api/credits

Output Schema

GET /api/videos

Query Parameters

Output Schema

GET /api/videos/:id

GET /api/videos/:id/status

Video Object Schema

`POST` /api/create

`GET` /api/voices

`GET` /api/credits

`GET` /api/videos

`GET` /api/videos/:id

`GET` /api/videos/:id/status