> ## Documentation Index > Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create speech understanding ## OpenAPI ````yaml specs/llm-gateway.yaml POST /understanding openapi: 3.1.0 info: title: AAI Chat Completions API description: API for generating text with various language models. version: 1.0.0 servers: - url: https://llm-gateway.assemblyai.com/v1 description: Production Server x-fern-server-name: Production security: - ApiKey: [] paths: /understanding: post: summary: Process speech understanding description: >- To use our EU server for LLM Gateway, replace `llm-gateway.assemblyai.com` with `llm-gateway.eu.assemblyai.com`. Perform various speech understanding tasks like [Translation](https://www.assemblyai.com/docs/speech-understanding/translation), [Speaker Identification](https://www.assemblyai.com/docs/speech-understanding/speaker-identification), and [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting). operationId: createSpeechUnderstanding requestBody: description: Request body for speech understanding tasks. required: true content: application/json: schema: $ref: '#/components/schemas/UnderstandingRequest' examples: translation_example: summary: Translation request value: transcript_id: '12345' speech_understanding: request: translation: target_languages: - es - de formal: true match_original_utterance: true speaker_identification_example: summary: Speaker identification request with known_values value: transcript_id: '12345' speech_understanding: request: speaker_identification: speaker_type: role known_values: - interviewer - candidate speaker_identification_with_speakers_example: summary: Speaker identification request with speakers metadata value: transcript_id: '12345' speech_understanding: request: speaker_identification: speaker_type: name speakers: - name: Michel Martin description: Hosts the program and interviews the guests company: NPR title: Host Morning Edition - name: Peter DeCarlo description: Answers questions from the interview company: Johns Hopkins University title: >- Professor and Vice Chair of Environmental Health and Engineering custom_formatting_example: summary: Custom formatting request value: transcript_id: '12345' speech_understanding: request: custom_formatting: date: mm/dd/yyyy phone_number: (xxx)xxx-xxxx email: username@domain.com responses: '200': description: Successful response containing the speech understanding results. content: application/json: schema: oneOf: - $ref: '#/components/schemas/LLMGatewayTranslationResponse' - $ref: >- #/components/schemas/LLMGatewaySpeakerIdentificationResponse - $ref: '#/components/schemas/LLMGatewayCustomFormattingResponse' - $ref: '#/components/schemas/LLMGatewaySummarizationResponse' examples: complete_response: summary: Complete response example value: speech_understanding: request: translation: target_languages: - es - de formal: true match_original_utterance: true speaker_identification: speaker_type: name speakers: - name: Michel Martin description: Hosts the program and interviews the guests company: NPR title: Host Morning Edition - name: Peter DeCarlo description: Answers questions from the interview company: Johns Hopkins University title: >- Professor and Vice Chair of Environmental Health and Engineering custom_formatting: date: mm/dd/yyyy phone_number: (xxx)xxx-xxxx email: username@domain.com summarization: summary_type: bullets response: summarization: status: success effort: low summary: - start: 0 end: 1000 bullets: - Host introduces Dr Peter DeCarlo - Asks for a quick intro - start: 1050 end: 3500 bullets: - Identifies key issues with the climate translation: status: success speaker_identification: mapping: A: Michel Martin B: Peter DeCarlo status: success custom_formatting: status: success mapping: '2024-12-25': 12/25/2024 555-1234-5678: (555)123-45678 formatted_text: Call me at (555)123-45678 on 12/25/2024 formatted_utterances: - confidence: 0.92 start: 0 end: 2500 text: >- Hi, I'm the interviewer. Call me at (555)123-45678 on 12/25/2024 speaker: interviewer - confidence: 0.95 start: 2500 end: 5000 text: Thanks! I'll reach out then. speaker: candidate translated_texts: es: >- Hola, soy el entrevistador. Llámame al cinco cinco cinco uno dos tres cuatro cinco seis siete ocho el veinticinco de diciembre de dos mil veinticuatro. ¡Gracias! Me pondré en contacto entonces. de: >- Hallo, ich bin der Interviewer. Rufen Sie mich an unter fünf fünf fünf eins zwei drei vier fünf sechs sieben acht am fünfundzwanzigsten Dezember zweitausendvierundzwanzig. Danke! Ich werde mich dann melden. utterances: - confidence: 0.92 start: 0 end: 2500 text: >- Hi, I'm the interviewer. Call me at five five five one two three four five six seven eight on December twenty fifth twenty twenty four speaker: interviewer translated_texts: es: >- Hola, soy el entrevistador. Llámame al cinco cinco cinco uno dos tres cuatro cinco seis siete ocho el veinticinco de diciembre de dos mil veinticuatro de: >- Hallo, ich bin der Interviewer. Rufen Sie mich an unter fünf fünf fünf eins zwei drei vier fünf sechs sieben acht am fünfundzwanzigsten Dezember zweitausendvierundzwanzig - confidence: 0.95 start: 2500 end: 5000 text: Thanks! I'll reach out then. speaker: candidate translated_texts: es: ¡Gracias! Me pondré en contacto entonces. de: Danke! Ich werde mich dann melden. words: [] default: description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: UnderstandingRequest: type: object properties: transcript_id: type: string description: The ID of the transcript to process. speech_understanding: type: object description: >- The speech understanding task to perform. Supports [Translation](https://www.assemblyai.com/docs/speech-understanding/translation), [Speaker Identification](https://www.assemblyai.com/docs/speech-understanding/speaker-identification), and [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting). Click into the request object below to see the available options. properties: request: oneOf: - $ref: '#/components/schemas/TranslationRequestBody' - $ref: '#/components/schemas/SpeakerIdentificationRequestBody' - $ref: '#/components/schemas/CustomFormattingRequestBody' - $ref: '#/components/schemas/SummarizationRequestBody' - $ref: '#/components/schemas/ActionItemsRequestBody' required: - request required: - transcript_id - speech_understanding LLMGatewayTranslationResponse: type: object properties: speech_understanding: type: object properties: request: $ref: '#/components/schemas/TranslationRequestBody' response: type: object properties: translation: type: object properties: status: type: string translated_texts: type: object description: >- Translated text keyed by language code (e.g., `{"es": "Texto traducido"}`) additionalProperties: type: string utterances: type: array description: >- Array of utterances with translations (when `match_original_utterance` is true) items: type: object properties: translated_texts: type: object description: >- Translations keyed by language code (e.g., `{"es": "Texto traducido", "de": "Übersetzter Text"}`). Only present when `match_original_utterance` is enabled. additionalProperties: type: string words: type: array items: type: object LLMGatewaySpeakerIdentificationResponse: type: object properties: speech_understanding: type: object properties: request: $ref: '#/components/schemas/SpeakerIdentificationRequestBody' response: type: object properties: speaker_identification: type: object properties: mapping: type: object description: >- A mapping of the original generic speaker labels (e.g., "A", "B") to the identified speaker names or roles. additionalProperties: type: string status: type: string required: - status utterances: type: array items: type: object words: type: array items: type: object LLMGatewayCustomFormattingResponse: type: object properties: speech_understanding: type: object properties: request: $ref: '#/components/schemas/CustomFormattingRequestBody' response: type: object properties: custom_formatting: type: object properties: mapping: type: object additionalProperties: type: string formatted_text: type: string formatted_utterances: type: array description: >- Array of formatted utterances. Only included when utterances exist and formatting was applied. items: type: object status: type: string required: - mapping - status utterances: type: array items: type: object LLMGatewaySummarizationResponse: type: object properties: speech_understanding: type: object properties: request: $ref: '#/components/schemas/SummarizationRequestBody' response: type: object properties: summarization: type: object properties: summary: type: array description: Array of summaries. items: type: object status: type: string required: - summary - status ErrorResponse: type: object properties: code: type: integer format: int32 description: HTTP status code for the error. message: type: string description: A human-readable description of the error. request_id: type: string format: uuid description: Unique identifier for the request. metadata: type: object description: >- Optional. Present on 400 responses with per-field validation details. properties: errors: type: array items: type: string description: List of specific validation failure messages. required: - code - message - request_id TranslationRequestBody: type: object description: >- Request body for [Translation](https://www.assemblyai.com/docs/speech-understanding/translation). properties: translation: type: object properties: target_languages: type: array items: type: string description: >- List of target language codes (e.g., `["es", "de"]`). See [Translation](https://www.assemblyai.com/docs/speech-understanding/translation) for supported languages. formal: type: boolean description: >- Use formal language style. See [Translation](https://www.assemblyai.com/docs/speech-understanding/translation) for more details. default: true match_original_utterance: type: boolean description: >- When enabled with Speaker Labels, returns translated text in the utterances array. Each utterance will include a `translated_texts` key containing translations for each target language. default: false required: - target_languages required: - translation SpeakerIdentificationRequestBody: type: object description: >- Request body for [Speaker Identification](https://www.assemblyai.com/docs/speech-understanding/speaker-identification). properties: speaker_identification: type: object properties: speaker_type: type: string enum: - role - name description: >- Type of speaker identification. See [Speaker Identification](https://www.assemblyai.com/docs/speech-understanding/speaker-identification) for details on each type. known_values: type: array items: type: string description: >- Required if speaker_type is "role". Each value must be 35 characters or less. speakers: type: array description: >- An array of speaker objects with metadata to improve identification accuracy. Each object should include a `role` or `name` (depending on `speaker_type`) and an optional `description` to help the model identify the speaker. You can also include any additional custom properties (e.g., `company`, `title`) to provide more context. Use this as an alternative to `known_values` when you want to provide additional context about each speaker. items: type: object properties: role: type: string description: >- The role of the speaker. Required when `speaker_type` is "role". name: type: string description: >- The name of the speaker. Required when `speaker_type` is "name". description: type: string description: >- A description of the speaker to help the model identify them based on conversational context. additionalProperties: true required: - speaker_type required: - speaker_identification CustomFormattingRequestBody: type: object description: >- Request body for [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting). properties: custom_formatting: type: object properties: date: type: string description: >- Date format pattern (e.g., `"mm/dd/yyyy"`). See [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting) for more details. phone_number: type: string description: >- Phone number format pattern (e.g., `"(xxx)xxx-xxxx"`). See [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting) for more details. email: type: string description: >- Email format pattern (e.g., `"username@domain.com"`). See [Custom Formatting](https://www.assemblyai.com/docs/speech-understanding/custom-formatting) for more details. required: - custom_formatting SummarizationRequestBody: type: object description: >- Request body for [Summarization](https://www.assemblyai.com/docs/speech-understanding/summarization). properties: summarization: type: object properties: summary_type: type: string enum: - paragraph - bullets description: >- Type of summary. Bullets returns short bullet point style summaries, paragraph is generally more verbose and detailed. effort: type: string enum: - low - medium required: - summary_type required: - summarization ActionItemsRequestBody: type: object description: >- Request body for [Action Items](https://www.assemblyai.com/docs/speech-understanding/action-items). properties: action_items: type: object properties: include_decisions: type: bool description: Option to include decision making in action items. effort: type: string enum: - low - medium required: - action_items securitySchemes: ApiKey: type: apiKey in: header name: Authorization ````