Ask questions about your media with the AI chat API

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.

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.

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.

All AI Chats

GET/prompt

Get AI Chat History.

Example request

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'

Response

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.

{
  "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"
      }
    ]
  }
}

Ask AI Chat

POST/prompt

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 rules. prompt is the only field you must send. assistantTemplateId becomes required when you set assistantType to custom; for every other value it is optional. You do not have to send folderId or mediaIds: a body with only prompt is accepted. Send one of them anyway, or the assistant has no material to read.

Streaming. Send isStream: true to get the answer as Server-Sent Events instead of one JSON body. The response comes back as text/event-stream with Cache-Control: no-cache and Connection: keep-alive. Every frame is written as data: <json> followed by a blank line, with no event: or id: field, so read them as default message events. The stream ends on an end frame, or an error frame if it failed, and there is no [DONE] sentinel. isStream: true cannot be combined with isIndividualPrompt: true; that returns 400 with errorCode STREAMING_NOT_SUPPORTED_FOR_INDIVIDUAL.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field	Type	Description
`prompt`	string, required	The question or instruction you want the AI to answer. Send a non-empty string, and be specific to get a useful answer. Required. the schema.required rejects an empty string. No maximum length.
`isStream`	boolean	Set this to true to stream the answer back as Server-Sent Events instead of waiting for one JSON response. Optional. Schema default is false, but see the note on defaults. When true, send an Accept header of text/event-stream. Cannot be combined with isIndividualPrompt set to true: the route returns 400 with errorCode STREAMING_NOT_SUPPORTED_FOR_INDIVIDUAL.
`folderId`	string	The folder you want the AI to read from. Everything in that folder becomes the context for your prompt. Optional. Accepts an empty string or null. Schema default is an empty string.
`mediaIds`	string[]	The specific media items you want the AI to read. Pass one or more media ids, even when you only have one. Optional. Accepts null and an empty array. No item cap and no per-item length limit.
`folderIds`	string[]	Several folders you want the AI to read from at once. Use this instead of folderId when the context spans more than one folder. Optional. Accepts null and an empty array. No item cap. No default.
`assistantType`	string	The assistant persona that shapes the answer. Use “general” unless you want a role-specific tone. Optional. Schema default is “general”. Important: the field is a bare the schema with.allow(AssistantTypes), which passes the enum object itself rather than spreading its members, so it adds no string values to the allowed set and imposes no restriction. Any non-empty string is accepted; an empty string is rejected with “assistantType is not allowed to be empty”; a non-string is rejected. The values listed here are the ones the product recognizes. Sending “custom” makes assistantTemplateId required. One of: `researcher`, `marketer`, `sales`, `general`, `recruiter`, `custom`.
`assistantTemplateId`	string	The id of your custom assistant template. Send this when you set assistantType to “custom”. Conditionally required: required when assistantType is “custom”, otherwise optional, accepts an empty string, and carries a schema default of an empty string. Does not accept null in either branch.
`tags`	string[]	Tags that narrow the media the AI reads to only items carrying those tags. Optional. Accepts null and an empty array. No item cap. No default.
`speakers`	string[]	Speaker names that narrow the transcript content the AI reads to only those speakers. Optional. Accepts null and an empty array. No item cap. No default.
`promptId`	string	The id of an existing chat you want to continue. Leave it out to start a new chat. Optional. Accepts an empty string or null. Schema default is an empty string.
`fieldId`	string	A single field you want the AI to fill or reference. Optional. Accepts an empty string. Does not accept null. No default.
`fieldIds`	string[]	Several fields you want the AI to fill or reference. Optional. Accepts null. Schema default is null. Maximum 10 items, and each item is at most 200 characters.
`isIndividualPrompt`	boolean	Set this to true to run the prompt separately against each media item instead of once across all of them. Optional. Schema default is false. Cannot be combined with isStream set to true; that combination returns 400.
`filters`	object	Extra filters that narrow which media the AI reads. Optional. Accepts null. The object’s keys are not validated, so any object is accepted at the top level. No default.
`startDate`	string	Only include media created on or after this date. Optional. Send an ISO 8601 date string or a timestamp. Accepts null and carries a schema default of null.
`endDate`	string	Only include media created on or before this date. Optional. Send an ISO 8601 date string or a timestamp. Accepts null and carries a schema default of null.
`modelId`	string	The language model you want to answer this chat. Leave it out, or send an empty string or null, to use your company default. The models Speak AI offers today are `gemini-2.5-flash`, `gemini-3-flash-preview`, `gemini-3.5-flash`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.5`, `gpt-5.4-mini-2026-03-17`, `claude-sonnet-5`, `claude-opus-4-8`, `claude-sonnet-4-6`, `x-ai/grok-4.5` and `z-ai/glm-5.2`. The full list below also holds older model ids that are still accepted so existing integrations keep working; treat those as deprecated and do not build against them. One of: `gpt-3.5`, `gpt-3.5-turbo-16k`, `gpt-3.5-turbo-0125`, `gpt-4`, `gpt-4-1106-preview`, `gpt-4-turbo`, `gpt-4o-2024-05-13`, `gpt-4o`, `gpt-4o-mini`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4.1-2025-04-14`, `gpt-5.1-2025-11-13`, `gpt-5.2`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.5-thinking`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `claude-2`, `claude-3-5-sonnet`, `claude-3-5-sonnet-20241022`, `claude-3-7-sonnet-latest`, `claude-haiku-4-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-opus-4-8`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-3-flash-preview`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3.5-flash`, `x-ai/grok-4.5`, `z-ai/glm-5.2`.
`attachments`	object[]	Images or PDFs you want the AI to look at alongside your prompt. Optional. Accepts null. Maximum 10 items. Each item is an object with the keys described below, and unknown keys inside an item are rejected. After schema validation the route checks that every attachment path is an S3 URL under your company’s prefix and returns 400 if it is not.
`attachments[].type`	string	The kind of file you are attaching. Required on every attachment. One of: `image`, `pdf`.
`attachments[].path`	string	The URL of the attached file, which must be a file your company owns. Required on every attachment. Must be a valid URI, and surrounding whitespace is trimmed. Ownership is checked after validation.
`attachments[].mimeType`	string	The MIME type of the attached file. Optional. Accepts an empty string or null. Whitespace is trimmed. Not restricted to a value list on this endpoint.
`attachments[].name`	string	A display name for the attached file. Optional. Accepts an empty string or null. Whitespace is trimmed.