# Synchronous generation

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Synchronous generation transcribes a recording and generates a note using the selected template. The HTTP response contains both results after processing completes.

## Endpoint

**`POST /aiservices/clinical_notes/generate`**

Authenticate with your [Zoom AI Services credentials](/docs/ai-services/auth/). The examples on this page send a token in the `Authorization: Bearer` header.

## Input

Provide a downloadable HTTPS or S3 URI in a JSON request, or upload a recording in the multipart `file` part.

| Field          | Type                     | Required | Description                                                                                                                                               |
| -------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`         | string or multipart file | Yes      | Downloadable HTTPS or S3 URI to the recording, or the uploaded file.                                                                                      |
| `template`     | string                   | No       | `SOAP`, `GENERAL_MEDICINE`, or `GENERAL_BEHAVIORAL_HEALTH`. Defaults to `GENERAL_MEDICINE` when omitted or empty. An unknown template returns HTTP `400`. |
| `reference_id` | string                   | No       | Optional client-supplied reference.                                                                                                                       |

Provide exactly one recording input. If transcription or note generation fails, the whole request fails.

| Limit             | Value                                       |
| ----------------- | ------------------------------------------- |
| Supported formats | `.wav`, `.mp3`, `.m4a`, `.mp4`, and `.webm` |
| Maximum duration  | 2 hours                                     |
| Maximum file size | 300 MB for uploads; 2 GB for URLs           |

### Example request (cURL)

This example uploads a recording and selects the SOAP template.

```shell
curl -X POST "https://api.zoom.us/v2/aiservices/clinical_notes/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@consultation.wav;type=audio/wav" \
  -F "template=SOAP"
```

For an HTTPS recording URL, send JSON instead:

```shell
curl -X POST "https://api.zoom.us/v2/aiservices/clinical_notes/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://example.com/consultation.wav",
    "template": "SOAP"
  }'
```

## Output

A successful request returns HTTP `200` and a JSON object with these fields.

| Field                               | Type           | Description                                                                                |
| ----------------------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `request_id`                        | string         | Request identifier.                                                                        |
| `transcript.text_display`           | string         | Complete transcript text.                                                                  |
| `transcript.duration_sec`           | number         | Audio duration in seconds. Included only when a duration is available.                     |
| `transcript.segments`               | object[]       | Time-aligned transcript segments, in order. Can be empty when segment data is unavailable. |
| `transcript.segments[].id`          | string         | Segment identifier.                                                                        |
| `transcript.segments[].start`       | number         | Segment start time in seconds.                                                             |
| `transcript.segments[].end`         | number         | Segment end time in seconds.                                                               |
| `transcript.segments[].channel`     | integer        | Audio channel index.                                                                       |
| `transcript.segments[].speaker`     | string         | Speaker label. Can be empty when unavailable.                                              |
| `transcript.segments[].text`        | string         | Recognized segment text.                                                                   |
| `transcript.segments[].words`       | object[]       | Word-level details. Can be empty.                                                          |
| `transcript.segments[].language`    | string or null | Language identified for the segment. Can be `null` when unavailable.                       |
| `clinical_notes.full_note`          | string         | Complete note formatted as Markdown.                                                       |
| `clinical_notes.sections`           | object[]       | Ordered note sections.                                                                     |
| `clinical_notes.sections[].title`   | string         | Section heading.                                                                           |
| `clinical_notes.sections[].content` | string         | Generated content for the section.                                                         |

`clinical_notes` is an object containing `full_note` and `sections`. Use the section array when your application displays headings and content separately.

### Display the transcript

-   Use `transcript.segments` to display the transcript as time-aligned segments, using each segment's `text`, `start`, and `end`.
-   Fall back to `transcript.text_display` when `segments` is empty.
-   An empty `speaker` or `words` array does not prevent transcript display.
-   Use `transcript.duration_sec` to display the audio duration when it is present. A missing `duration_sec` does not mean the recording has zero length.

### Example response

This response comes from a SOAP request that uses a synthetic clinical encounter. Generated content depends on the recording.

```json
{
    "request_id": "a99d32b7-87bf-44cc-a144-464fba16a592",
    "transcript": {
        "text_display": "Doctor, good morning. What brings you in today? Patient, I've had a sore throat and a fever or about 101 for three days. Doctor, any cough or trouble swallowing? Patient, some trouble swallowing, no cough. Doctor, your throat is red with swollen tonsils. A rapid strep test is positive. I'll prescribe amoxicillin 500 milligrams twice daily for 10 days. Drink fluids and follow up, if not better in 3 days.",
        "segments": [
            {
                "id": "utt_0000",
                "start": 0,
                "end": 10.944,
                "channel": 0,
                "speaker": "",
                "text": "Doctor, good morning. What brings you in today? Patient, I've had a sore throat and a fever or about 101 for three days. Doctor, any cough or trouble swallowing?",
                "words": [],
                "language": null
            },
            {
                "id": "utt_0001",
                "start": 10.944,
                "end": 29.564,
                "channel": 0,
                "speaker": "",
                "text": "Patient, some trouble swallowing, no cough. Doctor, your throat is red with swollen tonsils. A rapid strep test is positive. I'll prescribe amoxicillin 500 milligrams twice daily for 10 days. Drink fluids and follow up, if not better in 3 days.",
                "words": [],
                "language": null
            }
        ],
        "duration_sec": 29.564
    },
    "clinical_notes": {
        "full_note": "**Subjective**\n\nPatient presents with a sore throat and a fever of about 101 for three days. They report some trouble swallowing. They deny cough.\n\n**Objective**\n\n- **Exam:** Throat is red with swollen tonsils.\n- **Testing:** Rapid strep test is positive.\n\n**Assessment**\n\nStreptococcal pharyngitis, supported by sore throat, fever of about 101 for three days, trouble swallowing, red throat with swollen tonsils on exam, and positive rapid strep test.\n\n**Plan**\n\n- **Streptococcal pharyngitis:** Prescribed amoxicillin 500 milligrams twice daily for 10 days.\n- **Streptococcal pharyngitis/supportive care:** Advised to drink fluids.\n- **Streptococcal pharyngitis/follow-up:** Follow up if not better in 3 days.",
        "sections": [
            {
                "title": "Subjective",
                "content": "Patient presents with a sore throat and a fever of about 101 for three days. They report some trouble swallowing. They deny cough."
            },
            {
                "title": "Objective",
                "content": "- **Exam:** Throat is red with swollen tonsils.\n- **Testing:** Rapid strep test is positive."
            },
            {
                "title": "Assessment",
                "content": "Streptococcal pharyngitis, supported by sore throat, fever of about 101 for three days, trouble swallowing, red throat with swollen tonsils on exam, and positive rapid strep test."
            },
            {
                "title": "Plan",
                "content": "- **Streptococcal pharyngitis:** Prescribed amoxicillin 500 milligrams twice daily for 10 days.\n- **Streptococcal pharyngitis/supportive care:** Advised to drink fluids.\n- **Streptococcal pharyngitis/follow-up:** Follow up if not better in 3 days."
            }
        ]
    }
}
```

## Unsupported media

A recording URI without a supported file extension returns HTTP `400` with `reason` set to `UNSUPPORTED_MEDIA`. This includes a malformed URI that has no file extension.

```json
{
    "code": 400,
    "reason": "UNSUPPORTED_MEDIA",
    "message": "File extension \".jpg\" is not supported. Supported extensions: .m4a, .mp3, .mp4, .wav, .webm",
    "metadata": {}
}
```

## Request errors

If the request fails, the API returns one of these HTTP error codes.

| HTTP status | Reason                     | Condition                                                            |
| ----------- | -------------------------- | -------------------------------------------------------------------- |
| `400`       | `VALIDATION_MISSING_FIELD` | A JSON request does not include `file`.                              |
| `400`       | `INVALID_INPUT`            | A multipart request does not include a `file` part.                  |
| `400`       | `INVALID_INPUT`            | The template name is unknown.                                        |
| `400`       | `INVALID_INPUT`            | The recording can't be downloaded from the URI.                      |
| `400`       | `UNSUPPORTED_MEDIA`        | The recording URI does not have a supported media extension.         |
| `429`       | —                          | Too many requests. Retry after the time in the `Retry-After` header. |
| `500`       | —                          | Transcription or note generation failed.                             |
| `503`       | —                          | The service is temporarily unavailable.                              |

### Authentication errors

Missing or invalid authentication returns HTTP `401`. Authentication errors are separate from Clinical Notes application errors. Their response body uses a different shape, for example `{"code": 124, "message": "Invalid Access token"}`, and does not include `reason`.

See [Get credentials](/docs/ai-services/auth/) for authentication requirements.
