# 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.            |
| `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.

The Clinical Notes transcript contains `text_display`. It does not return transcript segments.

### Example response

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

```json
{
    "request_id": "bd89ab23-6e6c-439e-ab0f-19f07806b5a8",
    "transcript": {
        "text_display": "This is a fictional clinical encounter for API testing. The patient reports a mild headache since yesterday. The patient denies fever and nausea. No examination findings were recorded. The clinician plans a follow-up next week."
    },
    "clinical_notes": {
        "full_note": "**Subjective**\n\nPatient reports a mild headache since yesterday. They deny fever and nausea.\n\n**Objective**\n\nNo examination findings were recorded.\n\n**Assessment**\n\nMild headache since yesterday without reported fever or nausea. No explicit diagnosis beyond the reported symptom was documented.\n\n**Plan**\n\nFor mild headache, follow up next week.",
        "sections": [
            {
                "title": "Subjective",
                "content": "Patient reports a mild headache since yesterday. They deny fever and nausea."
            },
            {
                "title": "Objective",
                "content": "No examination findings were recorded."
            },
            {
                "title": "Assessment",
                "content": "Mild headache since yesterday without reported fever or nausea. No explicit diagnosis beyond the reported symptom was documented."
            },
            {
                "title": "Plan",
                "content": "For mild headache, follow up next week."
            }
        ]
    }
}
```

## Unsupported media

An input without a supported file extension returns HTTP `400` with `reason` set to `UNSUPPORTED_MEDIA`.

```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` | The recording input is missing.                                      |
| `400`       | `INVALID_INPUT`            | The template name is unknown or the input URI is invalid.            |
| `400`       | `UNSUPPORTED_MEDIA`        | The input 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. See [Get credentials](/docs/ai-services/auth/) for authentication requirements.