> ## Documentation Index
> Fetch the complete documentation index at: https://developers.x-pilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create conversation
> Creates a conversation and starts the first paid message immediately. Check credits and capacity first. By default the video is generated straight through; set require_outline_confirmation=true to review the outline first. Each files item may use an owned asset_id or a third-party public URL, with its own files_role. Billing matches the app: the platform reserve is held, released at the end, then actual usage is charged (a short balance is charged to 0, never negative). cost_credits is the held reserve until the message settles. Poll list messages at least 5 seconds apart; there is no streaming.
export const XpilotArticleMetadata = () => ;
export const XpilotBreadcrumb = () => ;
This request starts work that may consume workspace credits. Check credits and capacity before sending it.
Required scope: `video_agents:write`. A stable `Idempotency-Key` is required for exact retries.
[Manage API keys](https://app.x-pilot.ai/developers/console) · [Authentication and recovery](/api-reference)
export const XpilotDocFigure = () => REST requests use a scoped API key. Keys, credits and usage are managed in the App console.;
## OpenAPI
````yaml openapi.json POST /v1/video-agents/conversations
openapi: 3.0.3
info:
title: X-Pilot Developer API
version: 1.1.0
description: >-
Generated from the same public REST contract used by the X-Pilot app. REST
uses scoped API Keys. MCP OAuth tokens do not authenticate REST requests.
servers:
- url: https://api.x-pilot.ai
description: Production; confirm the deployed base URL in Developer Console.
security:
- BearerAuth: []
tags:
- name: Video Agent
- name: Renders
- name: Brand kits
- name: Account & capacity
- name: Assets
- name: Voices & audio
- name: Avatars
paths:
/v1/video-agents/conversations:
post:
tags:
- Video Agent
summary: Create conversation
description: >-
Creates a conversation and starts the first paid message immediately.
Check credits and capacity first. By default the video is generated
straight through; set require_outline_confirmation=true to review the
outline first. Each files item may use an owned asset_id or a
third-party public URL, with its own files_role. Billing matches the
app: the platform reserve is held, released at the end, then actual
usage is charged (a short balance is charged to 0, never negative).
cost_credits is the held reserve until the message settles. Poll list
messages at least 5 seconds apart; there is no streaming.
operationId: create-conversation
parameters:
- name: Idempotency-Key
in: header
required: true
description: >-
Stable key for exact retries only. Use a different key for a
different operation or input.
schema:
type: string
minLength: 8
maxLength: 128
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
description: >-
The brief: audience and goal first, then a # title and ##
sections with concrete facts, numbers, formulas, dates or
ordered steps. Each ## section becomes roughly one scene;
keep one video to about 12 scenes. Do not name visual
components. Up to 20,000 characters.
example: Create a short English lesson about solar energy.
maxLength: 20000
require_outline_confirmation:
type: boolean
description: >-
Default false: generate straight through with no pause.
true: the first message pauses with status=paused,
next_action=confirm_outline and an outline summary; then
send outline_action=confirm (no prompt needed) or
outline_action=revise with a prompt.
default: false
example: false
video_config:
type: object
description: >-
Video settings applied at creation; they cannot be changed
by a follow-up message. Unknown fields or unsupported values
return 400 invalid_parameter with param and allowed.
example:
target_language: en
video_duration: short
video_style: clean_lecture
properties:
target_language:
type: string
description: >-
Narration and subtitle language: ISO 639-1 code or
BCP-47 tag (en, zh, zh-CN, ja, de, fr, es…). Default en.
Changing it later means a new video.
default: en
video_duration:
type: string
description: 'short: 1–3 min. deep: 3–10 min. long: 10–20 min.'
enum:
- short
- deep
- long
default: short
video_style:
type: string
description: >-
auto lets the agent choose. clean_lecture: courses.
science_explainer: science processes.
professional_training: workplace training.
product_showcase: product demos. cinematic_story:
history and narrative.
enum:
- auto
- clean_lecture
- science_explainer
- professional_training
- product_showcase
- cinematic_story
default: auto
voice_id:
type: string
description: >-
Narration voice from list voices. Default picks a voice
for target_language.
voice_version:
type: integer
description: Version of voice_id. Requires voice_id.
enum:
- 1
- 2
default: 1
locale:
type: string
description: >-
Optional native locale of voice_id, for example en-US.
Requires voice_id.
avatar_id:
oneOf:
- type: string
- type: integer
description: >-
Presenter from list avatars. Must have selectable=true,
otherwise 409 avatar_not_ready.
brand_kit_id:
oneOf:
- type: string
- type: integer
description: Brand kit for logo, colors and tone.
enable_initial_ai_video:
type: boolean
description: Generate an AI opening clip when the plan allows it.
default: false
files:
type: array
description: >-
Up to 5 attachments. Each item uses either an owned asset_id
or a caller-supplied public http(s) URL. Third-party URLs
are downloaded and archived to the caller's storage before
use. Item fields: asset_id or url (required), name
(optional, ≤255), type (optional: document, image, video;
inferred when omitted), and files_role (optional: primary or
reference).
example:
- url: https://cdn.example.com/course.pdf
files_role: primary
items:
type: object
properties:
asset_id:
oneOf:
- type: string
- type: integer
description: id returned by POST /v1/assets or list assets.
url:
type: string
description: >-
Caller-supplied public http(s) URL. Third-party
content is archived before use.
name:
type: string
description: >-
Optional display name, up to 255 characters; inferred
when omitted.
type:
type: string
description: Optional; inferred from the file.
enum:
- document
- image
- video
files_role:
type: string
description: >-
How this file shapes the video. primary: use it as
main content and visual source. reference: use it only
as background facts. Omit to let the agent decide.
enum:
- primary
- reference
callback_url:
type: string
description: >-
Optional webhook for this message only. Public HTTPS (port
443) up to 2,048 characters; private, loopback and http
addresses return 400 invalid_webhook_url /
unsafe_webhook_url. When the message reaches completed,
paused, failed or stopped, X Pilot POSTs a
video-agent. event signed with the workspace
callback secret (Developer console → Webhooks). Deliveries
retry up to 6 times and are listed in the console.
example: https://your-domain.com/xpilot/callback
maxLength: 2048
callback_id:
type: string
description: >-
Optional reference echoed back as data.callback_id in the
callback, such as your order ID. Letters, digits, _ . : - up
to 128 characters. Requires callback_url.
example: order-1024
pattern: ^[\w.:-]{1,128}$
maxLength: 128
required:
- prompt
responses:
'202':
description: Success
content:
application/json:
example:
data:
conversation_id:
message_id:
status: running
cost_credits: 12
'400':
description: Check parameter types, required fields and idempotency key.
content:
application/json:
example:
error:
code: invalid_parameter
message: Check parameter types, required fields and idempotency key.
request_id:
'401':
description: Use an active scoped API Key. MCP OAuth tokens cannot call REST.
content:
application/json:
example:
error:
code: invalid_token
message: >-
Use an active scoped API Key. MCP OAuth tokens cannot call
REST.
request_id:
'402':
description: >-
The balance cannot cover the platform reserve, or the credential
monthly budget is used up.
content:
application/json:
example:
error:
code: insufficient_credits
message: >-
The balance cannot cover the platform reserve, or the
credential monthly budget is used up.
request_id:
'403':
description: Check the credential scope and resource ownership.
content:
application/json:
example:
error:
code: insufficient_scope
message: Check the credential scope and resource ownership.
request_id:
'409':
description: >-
The same idempotency key must use the exact same input. A
conversation may already be busy.
content:
application/json:
example:
error:
code: idempotency_conflict
message: >-
The same idempotency key must use the exact same input. A
conversation may already be busy.
request_id:
'429':
description: >-
Credential/workspace rate or concurrency limit reached. Respect
Retry-After before retrying.
content:
application/json:
example:
error:
code: rate_limited
message: >-
Credential/workspace rate or concurrency limit reached.
Respect Retry-After before retrying.
retry_after: 60
request_id:
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --fail-with-body --request POST \
--url "$XPILOT_API_BASE_URL/v1/video-agents/conversations" \
--header "Authorization: Bearer $XPILOT_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: lesson-request-001' \
--data '{"prompt":"Create a short English lesson about solar energy.","require_outline_confirmation":false,"video_config":{"target_language":"en","video_duration":"short","video_style":"clean_lecture"},"files":[{"url":"https://cdn.example.com/course.pdf","files_role":"primary"}],"callback_url":"https://your-domain.com/xpilot/callback","callback_id":"order-1024"}'
- lang: javascript
label: JavaScript
source: >-
const response = await fetch(process.env.XPILOT_API_BASE_URL +
"/v1/video-agents/conversations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPILOT_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "lesson-request-001",
},
body: JSON.stringify({
"prompt": "Create a short English lesson about solar energy.",
"require_outline_confirmation": false,
"video_config": {
"target_language": "en",
"video_duration": "short",
"video_style": "clean_lecture"
},
"files": [
{
"url": "https://cdn.example.com/course.pdf",
"files_role": "primary"
}
],
"callback_url": "https://your-domain.com/xpilot/callback",
"callback_id": "order-1024"
}),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
- lang: python
label: Python
source: |-
import os, json, requests
response = requests.request(
"POST",
os.environ["XPILOT_API_BASE_URL"] + "/v1/video-agents/conversations",
headers={
"Authorization": "Bearer " + os.environ["XPILOT_API_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": "lesson-request-001",
},
json=json.loads("{\"prompt\":\"Create a short English lesson about solar energy.\",\"require_outline_confirmation\":false,\"video_config\":{\"target_language\":\"en\",\"video_duration\":\"short\",\"video_style\":\"clean_lecture\"},\"files\":[{\"url\":\"https://cdn.example.com/course.pdf\",\"files_role\":\"primary\"}],\"callback_url\":\"https://your-domain.com/xpilot/callback\",\"callback_id\":\"order-1024\"}"),
timeout=70,
)
print(response.status_code, response.text)
response.raise_for_status()
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Scoped X-Pilot API key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
