> ## 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.
# Send message
> Send a follow-up turn to a conversation that is not running (409 conversation_busy otherwise). Paid. When next_action=confirm_outline, send outline_action=confirm (no prompt) or outline_action=revise with a prompt. When next_action=reply, answer with a prompt. Otherwise send an edit instruction. video_config and require_outline_confirmation are create-only (400 unsupported_parameter).
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/{conversation_id}
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/{conversation_id}:
post:
tags:
- Video Agent
summary: Send message
description: >-
Send a follow-up turn to a conversation that is not running (409
conversation_busy otherwise). Paid. When next_action=confirm_outline,
send outline_action=confirm (no prompt) or outline_action=revise with a
prompt. When next_action=reply, answer with a prompt. Otherwise send an
edit instruction. video_config and require_outline_confirmation are
create-only (400 unsupported_parameter).
operationId: send-message
parameters:
- name: conversation_id
in: path
required: true
description: An owned video agent conversation ID.
schema:
type: string
description: An owned video agent conversation ID.
- 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: false
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
description: >-
The edit instruction or the answer to the assistant.
Required unless outline_action=confirm; required with
outline_action=revise to describe the change. Up to 20,000
characters.
example: Make scene 2 shorter and add a worked example.
maxLength: 20000
outline_action:
type: string
description: >-
Only when next_action=confirm_outline. confirm continues
with the outline; revise rewrites it using prompt.
enum:
- confirm
- revise
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
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:
'404':
description: Use an existing owned conversation, message, brand kit or render ID.
content:
application/json:
example:
error:
code: not_found
message: >-
Use an existing owned conversation, message, brand kit or
render ID.
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/%3Cconversation_id%3E" \
--header "Authorization: Bearer $XPILOT_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: lesson-request-001' \
--data '{"prompt":"Make scene 2 shorter and add a worked example.","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/%3Cconversation_id%3E", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPILOT_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "lesson-request-001",
},
body: JSON.stringify({
"prompt": "Make scene 2 shorter and add a worked example.",
"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/%3Cconversation_id%3E",
headers={
"Authorization": "Bearer " + os.environ["XPILOT_API_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": "lesson-request-001",
},
json=json.loads("{\"prompt\":\"Make scene 2 shorter and add a worked example.\",\"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.
