Synchronous generation

View as Markdown

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

FieldTypeRequiredDescription
filestring or multipart fileYesDownloadable HTTPS or S3 URI to the recording, or the uploaded file.
templatestringNoSOAP, GENERAL_MEDICINE, or GENERAL_BEHAVIORAL_HEALTH. Defaults to GENERAL_MEDICINE when omitted or empty. An unknown template returns HTTP 400.
reference_idstringNoOptional client-supplied reference.

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

LimitValue
Supported formats.wav, .mp3, .m4a, .mp4, and .webm
Maximum duration2 hours
Maximum file size300 MB for uploads; 2 GB for URLs

Example request (cURL)

This example uploads a recording and selects the SOAP template.

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:

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.

FieldTypeDescription
request_idstringRequest identifier.
transcript.text_displaystringComplete transcript text.
transcript.duration_secnumberAudio duration in seconds. Included only when a duration is available.
transcript.segmentsobject[]Time-aligned transcript segments, in order. Can be empty when segment data is unavailable.
transcript.segments[].idstringSegment identifier.
transcript.segments[].startnumberSegment start time in seconds.
transcript.segments[].endnumberSegment end time in seconds.
transcript.segments[].channelintegerAudio channel index.
transcript.segments[].speakerstringSpeaker label. Can be empty when unavailable.
transcript.segments[].textstringRecognized segment text.
transcript.segments[].wordsobject[]Word-level details. Can be empty.
transcript.segments[].languagestring or nullLanguage identified for the segment. Can be null when unavailable.
clinical_notes.full_notestringComplete note formatted as Markdown.
clinical_notes.sectionsobject[]Ordered note sections.
clinical_notes.sections[].titlestringSection heading.
clinical_notes.sections[].contentstringGenerated 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.

{
  "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.

{
  "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 statusReasonCondition
400VALIDATION_MISSING_FIELDA JSON request does not include file.
400INVALID_INPUTA multipart request does not include a file part.
400INVALID_INPUTThe template name is unknown.
400INVALID_INPUTThe recording can't be downloaded from the URI.
400UNSUPPORTED_MEDIAThe 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 for authentication requirements.