---
title: "Ask questions about your media with the AI chat API"
description: "Ask a question about the media stored in Speak AI and read the answer back, and list the AI chat prompts that have already run in your account."
---

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

# Ask questions about your media with the AI chat API


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 2 ai chat endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Fetch all your Speak AI Chat Responses.

## What can you do with the ai chat endpoints?

Speak AI groups these 2 endpoints under the ai chat resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/prompt`](#get-prompt) | All AI Chats |
| `POST` | [`/prompt`](#post-prompt) | Ask AI Chat |

<h2 id="get-prompt">All AI Chats</h2>

Get AI Chat History.

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/prompt' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-prompt" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.totalCount` | integer |
| `data.pages` | integer |
| `data.history` | object[] |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (List of Prompts), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"totalCount": 2,
"pages": 1,
"history": [
  {
    "id": "64b04ce76db5f05cba07a3ff",
    "prompt": "Identify the top 5 action items to prioritize for maximum impact",
    "answer": "",
    "createdAt": "2023-07-13T19:13:43.953Z",
    "assistantType": "general",
    "mediaName": "How To Upload A Video File On Desktop",
    "mediaIds": [
      "de737309a4e9"
    ],
    "state": "failed",
    "link": "https://app.speakai.co/media/insight/MEDIA_URL"
  }
]
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-prompt">Ask AI Chat</h2>

AI Chat API allows you to run your own prompt via API.

`Prompt` (**required**) - It will be your query - please be as descriptive as possible to get an accurate output

`assistantType` (**default: general**) - Allow values are - general, researcher, marketer, sales, recruiter

`mediaIds` (**required**) - You can pass multiple `mediaIds` to run your prompt OR pass a single mediaId in an array

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `prompt` | string |
| `mediaIds` | string[] |
| `assistantType` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/prompt' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "Tell me how my speaking pace was. Did I speak too fast, at a good pace or too slowly? A good pace is between 140 and 170 words per minute. Less than 140 words per minute is too slow and more than 170",
  "mediaIds": [
"923884998a91"
  ],
  "assistantType": "general"
}'
```

</CodePanel>

<ResponsePanel id="post-prompt" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.state` | string |
| `data.answer` | string |
| `data.totalMedia` | integer |
| `data.references` | any[] |

Example response (Success Response), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"state": "completed",
"answer": "Main discussion points:\n\n- The video demonstrates how to upload a video file through Speak.\n- The process involves signing in, accessing the dashboard, and hitting the upload butto...",
"totalMedia": 1,
"references": []
  }
}
```

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-ai-chat).

Source: https://docs.speakai.co/api/ai-chat/index.mdx