Sofer.AI Daf Shiur Transcription Workflow free

reviewed by skillbay: we re-ran the example ourselves and the skill changed the answer. see our run

Shape, run, resume, and safely debug Sofer.AI express or standard transcription batches for Daf Yomi and Hebrew shiur audio.

before and after

the same prompt, answered without the skill and then with it.

Using the Sofer.AI API, I have the audio URL https://example.com/audio/daf-yomi-shiur.mp3. Show the exact request body and safe next steps for one immediate Daf Yomi transcription, but do not make a network call or expose any credentials.

Set SOFER_API_KEY in your environment, then send a POST request to Sofer.AI with the audio URL. A typical request might look like:

```json
{
  "audio_url": "https://example.com/audio/daf-yomi-shiur.mp3",
  "language": "en"
}
```

After creating the transcription, save the returned ID and poll `/v1/transcriptions/{id}` until it is complete, then retrieve the transcript. You can use a batch endpoint if you have multiple files. Do not print the API key. If the request fails, check the key and the URL.

Do not make a network call. First confirm the audio URL and cost authorization; this request still needs `SOFER_API_KEY` before live use. For immediate work, use express batch mode:

```json
{
  "info": {
    "model": "v1",
    "primary_language": "en",
    "hebrew_word_format": ["en", "he"],
    "num_speakers": 1
  },
  "processing_mode": "express",
  "audio_sources": [
    {
      "audio_url": "https://example.com/audio/daf-yomi-shiur.mp3",
      "title": "Daf Yomi Shiur",
      "client_item_id": "daf-yomi-shiur"
    }
  ],
  "batch_title": "Daf Yomi Shiur"
}
```

Call `POST https://api.sofer.ai/v1/transcriptions/batch` with `Authorization: Bearer $SOFER_API_KEY`. Persist `batch_id`, `transcription_ids`, and `client_item_id` from the response. Poll batch status before assuming completion, then retrieve each transcript with `GET https://api.sofer.ai/v1/transcriptions/{transcription_id}`. If the key is missing, stop and report `SOFER_API_KEY`; handle 401 as an invalid key, 429 as a rate limit, and a missing audio URL by asking for `YUTORAH_AUDIO_URL`.

The working directory has no Sofer.AI spec, and with no network call allowed I cannot verify the endpoint path or exact field names. So the body below is a template built from what you stated, with every field that needs confirmation against the Sofer.AI docs marked. Nothing here was sent anywhere and no key is included.

**Request body (JSON, for a single non-batch transcription)**

```json
{
  "audio_url": "https://example.com/audio/daf-yomi-shiur.mp3",
  "mode": "immediate",
  "content_type": "daf_yomi",
  "primary_language": "en",
  "additional_languages": ["he", "arc"],
  "output_format": "json",
  "metadata": {
    "title": "Daf Yomi shiur",
    "source": "daf-yomi-shiur.mp3"
  }
}
```

**What is fixed versus what you must confirm**

- Fixed by your request: the audio URL, one job only, immediate rather than batch.
- Confirm in the docs: the exact key names. Sofer.AI may spell these `url`, `priority`, `speedup`, `primary_language`, or use a Hebrew/Aramaic-aware "Torah" preset instead of a content type field. Do not send the template until the names match the published schema.
- Confirm the endpoint and verb. I have not verified the path, so treat it as `POST <base_url>/<transcribe endpoint>` until you read it from the docs.
- Confirm the auth header format. It is typically a bearer token or an `x-api-key` header, and the docs decide which.

**Safe next steps, in order**

1. Read the Sofer.AI API reference for the transcription create endpoint and copy its field names into the template above.
2. Put the key in an environment variable, for example `SOFER_API_KEY`, and never paste it into a shell history, a file in this repo, or a chat message.
3. Confirm the audio URL is publicly fetchable by the Sofer.AI servers. Example.com will not serve real audio, so swap in the real host before the live call.
4. Do one dry run with the body written to a file and printed back, no network. For example:

```bash
cat > /tmp/sofer-request.json <<'EOF'
{ ...the body above, with confirmed field names... }
EOF
python3 -m json.tool /tmp/sofer-request.json
```

5. When you are ready to send, use the env var in the header and reference the file, so the key never appears in the command text:

```bash
curl -sS -X POST "$SOFER_BASE_URL/<confirmed endpoint>" \
  -H "Authorization: Bearer $SOFER_API_KEY" \
  -H "Content-Type: application/json" \
  --data @/tmp/sofer-request.json
```

6. Capture the returned job or transcript ID, then poll the status endpoint the docs specify rather than retrying the create call. Retrying create would bill you for a second transcription.
7. Check the response for Hebrew and Aramaic term handling on a short sample before running a full shiur, since Daf Yomi content is where transliteration settings matter most.

If you want me to turn this into a small script in this repo, point me at the Sofer.AI docs page or paste the schema, and I will match the field names exactly.

No network call was made and no credentials were read or printed. The body below came from the skill's local shaping script.

**Request**

```
POST https://api.sofer.ai/v1/transcriptions/batch
Authorization: Bearer $SOFER_API_KEY
Content-Type: application/json
```

```json
{
  "info": {
    "model": "v1",
    "primary_language": "en",
    "hebrew_word_format": ["en", "he"],
    "num_speakers": 1
  },
  "processing_mode": "express",
  "audio_sources": [
    {
      "audio_url": "https://example.com/audio/daf-yomi-shiur.mp3",
      "title": "Daf Yomi Shiur",
      "client_item_id": "daf-yomi-shiur"
    }
  ],
  "batch_title": "Daf Yomi Shiur"
}
```

Express mode is the right choice for one immediate transcription. Standard mode needs a manifest upload first and completes more slowly. The two-language Hebrew word format keeps both transliterated and Hebrew-script terms, which matters for a daf shiur. Set num_speakers higher if the recording includes questions from the audience.

**Safe next steps, in order**

1. **Confirm the audio URL is real.** The example.com address is a placeholder. Swap in the actual shiur URL before anything else, and make sure it is publicly fetchable by Sofer.
2. **Provide the key through the environment only.** Export SOFER_API_KEY in your shell or a local dotenv file that is gitignored. Never paste it into the JSON, a script, or a chat.
3. **Send the request** with a tool that reads the key from the environment, for example:
   ```
   curl -sS -X POST https://api.sofer.ai/v1/transcriptions/batch \
     -H "Authorization: Bearer $SOFER_API_KEY" \
     -H "Content-Type: application/json" \
     -d @request.json
   ```
4. **Persist the IDs immediately.** The response returns a batch ID and a list of transcription IDs. Save them alongside the client item id in your project report so polling can resume after a restart.
5. **Poll batch status** until it reports complete, then fetch the transcript from the per-transcription endpoint:
   ```
   GET https://api.sofer.ai/v1/transcriptions/{transcription_id}
   ```
6. **Store the raw Sofer JSON separately** from any normalized text you derive. Prefer timestamped segments and speaker labels, and fall back to the full transcript text only if those are absent.

**Error handling.** A 401 means the key is missing or invalid, so check the environment variable before retrying. A 429 is a rate limit, so back off rather than looping. If the batch is not complete yet, keep polling with the saved batch ID instead of re-submitting, which would bill a second transcription.

about this skill

SKILL.md

---
name: sofer-api
description: "Use when working with Sofer.AI transcription APIs: creating express or standard batch transcriptions, shaping audio source requests, polling batch/transcription status, retrieving transcript JSON, handling SOFER_API_KEY, persisting job IDs, or debugging Sofer transcript workflows."
---

# Sofer API

Use this skill for Sofer.AI transcription work. Keep live calls gated on `SOFER_API_KEY`; never invent credentials.

## Workflow

1. Confirm input audio URL and whether the user wants live API cost.
2. Require `SOFER_API_KEY` before calling `https://api.sofer.ai`.
3. For immediate work, use express batch mode with `audio_sources`; for lower-cost bulk work, use standard mode with a manifest.
4. Persist `batch_id`, `transcription_ids`, and `client_item_id` in the project report so polling can resume.
5. Poll batch/transcription status until complete, then retrieve transcript JSON.
6. If blocked by missing key, missing audio URL, rate limit, or incomplete job, report the exact env var/job ID/next input needed.

## Request Shaping

Use `scripts/shape_express_batch.py` to generate a deterministic express request body without making a network call.

Read `references/endpoints.md` when exact endpoint paths, request fields, or response IDs matter.

## Transcript Handling

Prefer structured transcript fields when available:

- segment text with timestamps
- speaker labels if returned
- full transcript text as fallback
- raw Sofer JSON stored separately from normalized alignment text

package contents

post id: bx5wvyskfatdkjbs