From 26b640b90536c84e213d1ef2b3d51738ec4bc013 Mon Sep 17 00:00:00 2001
From: Rishabh Bhargava <rishabh.bhargava93@gmail.com>
Date: Mon, 11 May 2026 13:57:24 -0700
Subject: [PATCH] ENG-87567 docs: document audio transcription batches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an enum on CreateBatchRequest.endpoint covering all three supported
values (chat completions plus audio transcriptions and translations) and
two x-codeSamples (Python + cURL) demonstrating audio batch creation.
The Python sample includes the per-line JSONL shape with `"method": "FILE"`,
which is required for audio batches today.

Surfaces the audio batch contract that previously only existed in code.
Coordinates with ENG-87568 (service fix to drop the method:"FILE"
requirement) — if that lands first the JSONL example here will be
simplified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 openapi.yaml | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index 72d0e8c..c96265a 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -6117,6 +6117,38 @@ paths:
                    "endpoint": "/v1/chat/completions",
                    "input_file_id": "file-id"
                  }'
+        - lang: Python
+          label: Audio transcriptions (Python)
+          source: |
+            # Audio transcription batches use the /v1/audio/transcriptions endpoint.
+            # Each line in the uploaded JSONL must include `"method": "FILE"` so the
+            # worker dispatches the request as multipart/form-data. Example line:
+            #   {"custom_id": "transcription-1", "method": "FILE",
+            #    "body": {"file": "https://example.com/audio.wav",
+            #             "model": "openai/whisper-large-v3"}}
+            from together import Together
+            import os
+
+            client = Together(
+                api_key=os.environ.get("TOGETHER_API_KEY"),
+            )
+
+            batch = client.batches.create(
+                input_file_id="file_id",
+                endpoint="/v1/audio/transcriptions",
+            )
+
+            print(batch.job)
+        - lang: Shell
+          label: Audio transcriptions (cURL)
+          source: |
+            curl -X POST "https://api.together.ai/v1/batches" \
+                 -H "Authorization: Bearer $TOGETHER_API_KEY" \
+                 -H "Content-Type: application/json" \
+                 -d '{
+                   "endpoint": "/v1/audio/transcriptions",
+                   "input_file_id": "file-id"
+                 }'
       security:
         - bearerAuth: []
       requestBody:
@@ -12296,7 +12328,15 @@ components:
       properties:
         endpoint:
           type: string
-          description: The endpoint to use for batch processing
+          enum:
+            - /v1/chat/completions
+            - /v1/audio/transcriptions
+            - /v1/audio/translations
+          description: |
+            The endpoint to use for batch processing. Each line of the uploaded input file is dispatched against this endpoint.
+            - `/v1/chat/completions` — chat completion batches
+            - `/v1/audio/transcriptions` — audio transcription batches (e.g. `openai/whisper-large-v3`)
+            - `/v1/audio/translations` — audio translation batches
           example: '/v1/chat/completions'
         input_file_id:
           type: string