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

# Generate Video

> Trigger AI-powered demo video generation for a domain.

Submit a video generation job for a given domain. Demomatic uses your prompt to autonomously record the application, generate narration, and assemble the final video.

Most requests are queued and processed asynchronously. Poll `GET /v1/videos` to check for the completed video. In some environments, the video may be returned synchronously in the same response.

## Endpoint

```
POST /v1/videos/:domain_id
```

## Authentication

Pass an `all_access` API key as a Bearer token in the `Authorization` header.

<ParamField header="Authorization" type="string" required>
  Your API key. Format: `Bearer <api_key>`. Must have `all_access` permission — read-only keys cannot call this endpoint.
</ParamField>

<Warning>
  Read-only API keys cannot call this endpoint. You must use a key with `all_access` permission.
</Warning>

## Path parameters

<ParamField path="domain_id" type="number" required>
  The ID of the domain to generate a video for. The domain must belong to your account.
</ParamField>

## Request body

<ParamField body="prompt" type="string">
  Natural language description of the demo to generate. Describe the user flow, feature, or scenario you want to showcase.
</ParamField>

<ParamField body="font" type="string" required>
  Font to use for captions and text overlays. Valid values: `"Inter"`, `"OpenSans"`, `"Playwrite"`, `"Poppins"`, `"Roboto"`.
</ParamField>

<ParamField body="captions" type="boolean" required>
  When `true`, captions are added to the video.
</ParamField>

<ParamField body="bRoll" type="boolean" required>
  When `true`, B-roll footage is included in the video.
</ParamField>

<ParamField body="music" type="string">
  Background music track. Valid values: `"observer"`, `"lawrence"`, `"all_i_am"`, `"lust"`, `"denied_access"`, `"75_and_lower"`. Omit to use no music.
</ParamField>

<ParamField body="voiceId" type="string | null">
  Voice model for narration. Valid values: `"ash"`, `"onyx"`, `"nova"`, `"fable"`. Pass `null` to omit narration.
</ParamField>

<ParamField body="backgroundId" type="string | null">
  Background style ID. Pass `null` to use no custom background.
</ParamField>

<ParamField body="contacts" type="object[]">
  List of recipient contacts used to personalize the video narration and on-screen text.

  <Expandable title="contact properties">
    <ResponseField name="email" type="string">
      Recipient's email address. Required if you want to notify them after generation.
    </ResponseField>

    <ResponseField name="name" type="string">
      Recipient's full name.
    </ResponseField>

    <ResponseField name="jobTitle" type="string">
      Recipient's job title.
    </ResponseField>

    <ResponseField name="company" type="string">
      Recipient's company name.
    </ResponseField>

    <ResponseField name="industry" type="string">
      Recipient's industry.
    </ResponseField>

    <ResponseField name="additionalNotes" type="string">
      Any additional context to incorporate into the personalization.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="notify_contacts" type="boolean">
  When `true`, contacts with a valid `email` are emailed a link to the video after generation completes. Defaults to `false`.
</ParamField>

## Response

Generation requests are almost always queued. The response shape depends on whether the job was queued or completed synchronously.

### Queued response

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="job_id" type="number" required>
      ID of the queued video job. Use this to correlate status when polling.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Job status. Always `"queued"` for this response shape.
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Human-readable message with polling instructions. Poll `GET /v1/videos` until the new video appears.
    </ResponseField>
  </Expandable>
</ResponseField>

### Synchronous response

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="video" type="object" required>
      <Expandable title="video properties">
        <ResponseField name="id" type="number" required>
          Unique video identifier.
        </ResponseField>

        <ResponseField name="domain_id" type="number" required>
          ID of the domain this video was generated for.
        </ResponseField>

        <ResponseField name="filename" type="string" required>
          Human-readable name assigned to the video.
        </ResponseField>

        <ResponseField name="url" type="string" required>
          Pre-signed URL to stream or download the video.
        </ResponseField>

        <ResponseField name="created_at" type="string" required>
          ISO 8601 timestamp when the video was created.
        </ResponseField>

        <ResponseField name="updated_at" type="string" required>
          ISO 8601 timestamp when the video was last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Description                                                                      |
| ------ | -------------------------------------------------------------------------------- |
| `400`  | The `domain_id` is not a valid number, or the request body failed validation.    |
| `404`  | No domain found with the given ID, or the domain belongs to a different account. |

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.demomatic.tech/v1/videos/45 \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "prompt": "Show how a user signs up and completes onboarding",
      "font": "Poppins",
      "captions": true,
      "bRoll": false,
      "music": "observer",
      "voiceId": null,
      "backgroundId": null
    }'
  ```

  ```javascript JavaScript theme={null}
  const domainId = 45;

  const response = await fetch(`https://api.demomatic.tech/v1/videos/${domainId}`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'Show how a user signs up and completes onboarding',
      font: 'Poppins',
      captions: true,
      bRoll: false,
      music: 'observer',
      voiceId: null,
      backgroundId: null,
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Queued response

```json 200 theme={null}
{
  "data": {
    "job_id": 789,
    "status": "queued",
    "message": "Video job queued. Poll GET /v1/videos or GET /jobs/:domain_id for completion."
  }
}
```

### Synchronous response

```json 200 theme={null}
{
  "data": {
    "video": {
      "id": 123,
      "domain_id": 45,
      "url": "https://signed-url.example.com/video.mp4",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:05:00.000Z",
      "filename": "Product Tour"
    }
  }
}
```

### Personalized generation with contacts

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.demomatic.tech/v1/videos/45 \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "prompt": "Showcase the analytics dashboard",
      "font": "Poppins",
      "captions": true,
      "bRoll": false,
      "contacts": [
        {
          "name": "Alice Smith",
          "email": "alice@example.com",
          "jobTitle": "Head of Marketing",
          "company": "Acme Corp",
          "industry": "SaaS"
        }
      ],
      "notify_contacts": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const domainId = 45;

  const response = await fetch(`https://api.demomatic.tech/v1/videos/${domainId}`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'Showcase the analytics dashboard',
      font: 'Poppins',
      captions: true,
      bRoll: false,
      contacts: [
        {
          name: 'Alice Smith',
          email: 'alice@example.com',
          jobTitle: 'Head of Marketing',
          company: 'Acme Corp',
          industry: 'SaaS',
        },
      ],
      notify_contacts: true,
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```
</CodeGroup>