> ## Documentation Index
> Fetch the complete documentation index at: https://docs.babou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Prompt

> Submit a text prompt to create video content for a chapter

## Overview

Submit a prompt to a chapter, describing what to build. The system processes the prompt and creates the chapter content, typically completing in 30-90 seconds.

<Info>
  If a chapter already has a prompt being processed, this endpoint returns a `409 Conflict` error unless you set `force: true` to override.
</Info>

## Request

### Path Parameters

<ParamField path="projectId" type="string" required>
  The project ID
</ParamField>

<ParamField path="chapterId" type="string" required>
  The chapter ID
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body

<ParamField body="content" type="string" required>
  The prompt text describing the video content you want to create (1-5000 characters)
</ParamField>

<ParamField body="force" type="boolean" default="false">
  Force processing even if another prompt is already being processed for this chapter
</ParamField>

## Response

<ResponseField name="prompt_id" type="string">
  Unique identifier for the submitted prompt
</ResponseField>

<ResponseField name="status" type="string">
  Processing status: `processing`, `completed`, or `failed`
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="estimated_time" type="string">
  Estimated processing time (e.g., "30-90 seconds")
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.babou.ai/api/v1/projects/prj_abc123xyz/chapters/cht_def456uvw/prompt \
    -H "Authorization: Bearer $BABOU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "30-second product launch ad for the new Team tier. Lead with the headline from our latest release notes, drop in the new pricing screenshot, and resolve brand colors and type from the catalog."
    }'
  ```

  ```typescript TypeScript theme={null}
  async function submitPrompt(
    projectId: string,
    chapterId: string,
    content: string,
    force = false
  ) {
    const response = await fetch(
      `https://api.babou.ai/api/v1/projects/${projectId}/chapters/${chapterId}/prompt`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.BABOU_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ content, force })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Failed to submit prompt: ${error.error}`);
    }

    return await response.json();
  }

  const result = await submitPrompt(
    'prj_abc123xyz',
    'cht_def456uvw',
    'Product launch ad for the new Team tier, pulling the headline from our release notes'
  );

  console.log(`Prompt submitted: ${result.status}`);
  console.log(`Estimated time: ${result.estimated_time}`);
  ```

  ```python Python theme={null}
  import os
  import requests

  def submit_prompt(project_id, chapter_id, content, force=False):
      response = requests.post(
          f'https://api.babou.ai/api/v1/projects/{project_id}/chapters/{chapter_id}/prompt',
          headers={
              'Authorization': f'Bearer {os.environ["BABOU_API_KEY"]}',
              'Content-Type': 'application/json'
          },
          json={'content': content, 'force': force}
      )

      if not response.ok:
          error = response.json()
          raise Exception(f'Failed to submit prompt: {error["error"]}')

      return response.json()

  result = submit_prompt(
      'prj_abc123xyz',
      'cht_def456uvw',
      'Product launch ad for the new Team tier, pulling the headline from our release notes'
  )

  print(f'Prompt submitted: {result["status"]}')
  print(f'Estimated time: {result["estimated_time"]}')
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "prompt_id": "int_abc123xyz789",
  "status": "processing",
  "message": "Prompt processing started",
  "estimated_time": "30-90 seconds"
}
```

## Error Responses

<ResponseField name="VALIDATION_ERROR" type="400">
  Invalid prompt content

  ```json theme={null}
  {
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "hint": "Content must be between 1 and 5000 characters"
  }
  ```
</ResponseField>

<ResponseField name="CONFLICT" type="409">
  Another prompt is already being processed for this chapter

  ```json theme={null}
  {
    "error": "A prompt is already being processed for this chapter",
    "code": "CONFLICT",
    "hint": "Wait for the current prompt to complete or set force: true to override"
  }
  ```
</ResponseField>

<ResponseField name="NOT_FOUND" type="404">
  Project or chapter not found

  ```json theme={null}
  {
    "error": "Chapter not found",
    "code": "NOT_FOUND"
  }
  ```
</ResponseField>

## Best Practices

<AccordionGroup>
  <Accordion title="Write clear, descriptive prompts">
    Be specific about what you want in your video. Include details about:

    * Visual style and aesthetics
    * Text content and messaging
    * Transitions and animations
    * Mood and tone

    ```typescript theme={null}
    const prompt = `
    30-second product launch ad for the new Team tier.
    - Lead with the headline from our latest release notes
    - Show the updated pricing screenshot at 5s
    - Resolve brand colors and type from the catalog
    - Close on a CTA matching the pricing page button
    `;

    await submitPrompt(projectId, chapterId, prompt);
    ```
  </Accordion>

  <Accordion title="Wait for processing to complete">
    After submitting a prompt, the video content is created asynchronously. Use the [Get Chapter](/api-reference/chapters/get) endpoint to check when processing is complete:

    ```typescript theme={null}
    async function waitForPromptCompletion(
      projectId: string,
      chapterId: string,
      maxAttempts = 20
    ) {
      for (let i = 0; i < maxAttempts; i++) {
        const chapter = await getChapter(projectId, chapterId);
        const latestPrompt = chapter.prompts[chapter.prompts.length - 1];

        if (latestPrompt.status === 'completed') {
          return latestPrompt;
        }

        if (latestPrompt.status === 'failed') {
          throw new Error('Prompt processing failed');
        }

        await new Promise(r => setTimeout(r, 5000)); // Wait 5s
      }

      throw new Error('Timeout waiting for prompt completion');
    }
    ```
  </Accordion>

  <Accordion title="Handle conflicts gracefully">
    If you get a 409 error, decide whether to:

    1. Wait for the current prompt to complete
    2. Override with `force: true` (use cautiously)

    ```typescript theme={null}
    async function submitPromptSafe(
      projectId: string,
      chapterId: string,
      content: string
    ) {
      try {
        return await submitPrompt(projectId, chapterId, content);
      } catch (error: any) {
        if (error.message.includes('already being processed')) {
          console.log('Waiting for current prompt to complete...');
          await waitForPromptCompletion(projectId, chapterId);
          // Retry submission
          return await submitPrompt(projectId, chapterId, content);
        }
        throw error;
      }
    }
    ```
  </Accordion>

  <Accordion title="Reference uploaded assets">
    If you've uploaded assets, reference them in your prompts:

    ```typescript theme={null}
    // Upload asset first
    const logo = await uploadAsset('./company-logo.png', 'image/png');

    // Reference in prompt
    const prompt = `
    Create an intro video using the uploaded company logo (${logo.url}).
    Animate the logo with a fade-in effect over 3 seconds.
    Add the text "Welcome" below the logo.
    `;

    await submitPrompt(projectId, chapterId, prompt);
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Chapter" icon="eye" href="/api-reference/chapters/get">
    Check processing status
  </Card>

  <Card title="Export Project" icon="file-export" href="/api-reference/exports/start">
    Export your completed video
  </Card>

  <Card title="Video Creation Guide" icon="diagram-project" href="/guides/video-creation-workflow">
    Learn more about creating videos
  </Card>
</CardGroup>