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"}'

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);

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()

{
  "data": {
    "conversation_id": "<conversation_id>",
    "message_id": "<message_id>",
    "status": "running",
    "cost_credits": 12
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Check parameter types, required fields and idempotency key."
  },
  "request_id": "<request_id>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "Use an active scoped API Key. MCP OAuth tokens cannot call REST."
  },
  "request_id": "<request_id>"
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "The balance cannot cover the platform reserve, or the credential monthly budget is used up."
  },
  "request_id": "<request_id>"
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "Check the credential scope and resource ownership."
  },
  "request_id": "<request_id>"
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The same idempotency key must use the exact same input. A conversation may already be busy."
  },
  "request_id": "<request_id>"
}

{
  "error": {
    "code": "rate_limited",
    "message": "Credential/workspace rate or concurrency limit reached. Respect Retry-After before retrying.",
    "retry_after": 60
  },
  "request_id": "<request_id>"
}