Skip to content

reference.md

Latest commit

 

History

History
2557 lines (1785 loc) · 33.4 KB

reference.md

File metadata and controls

2557 lines (1785 loc) · 33.4 KB
Raw

Reference

Balance

client.balance.get_balance()

📝 Description

Get account balance showing available balance and pending charges

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.balance.get_balance()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

BatchTranscribe

client.batch_transcribe.create_batch_transcription(...)

📝 Description

Create multiple transcriptions in a single batch request.

Choose a processing mode:

  • Express mode: Transcriptions start immediately. Max 10 files. Higher cost. Pass audio_sources directly in the request. Pricing for v1 is $1.20/hour.
  • Standard mode: Transcriptions processed within 24 hours. Max 500 files. Lower cost. First upload a manifest via Upload Batch Manifest File, then pass the batch_file_id here. Pricing for v1 batch standard is $0.90/hour.

All files in the batch share the same transcription settings (model, language, etc.) defined in info.

🔌 Usage

import uuid

from soferai import SoferAI
from soferai.transcribe import TranscriptionRequestInfo

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.batch_transcribe.create_batch_transcription(
    batch_file_id=uuid.UUID(
        "f1234567-89ab-cdef-0123-456789abcdef",
    ),
    info=TranscriptionRequestInfo(
        model="v1",
        primary_language="en",
        hebrew_word_format=["en", "he"],
        num_speakers=1,
    ),
    batch_title="Weekly Shiurim Collection",
    processing_mode="standard",
)

⚙️ Parameters

info: TranscriptionRequestInfo — Transcription settings applied to all files in the batch (model, language, etc.)

processing_mode: typing.Optional[ProcessingMode]

Choose how the batch is processed:

  • standard (default): Lower cost, processed within 24 hours. Max 500 files. Use with batch_file_id. Pricing for v1 batch standard is $0.90/hour.
  • express: Higher cost, starts immediately. Max 10 files. Use with audio_sources. Pricing for v1 is $1.20/hour.

batch_file_id: typing.Optional[uuid.UUID]

For standard mode only. ID of a previously uploaded batch manifest.

Get this by calling Upload Batch Manifest File first.

audio_sources: typing.Optional[typing.Sequence[BatchAudioSource]]

For express mode only. List of audio URLs to transcribe (max 10).

Each item needs an audio_url and can optionally include a title.

batch_title: typing.Optional[str] — Default title prefix for transcriptions. Individual items can override this. Items without titles become "{batch_title} - Item 1", "{batch_title} - Item 2", etc.

batch_id: typing.Optional[uuid.UUID] — Custom UUID for this batch. Auto-generated if not provided.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch_transcribe.upload_batch_file(...)

📝 Description

Upload a batch manifest containing audio URLs for standard mode batch processing.

Workflow:

  1. Upload your manifest here to get a batch_file_id
  2. Use that ID in Create Batch Transcription with processing_mode: "standard"

The manifest is a list of audio sources (max 500), each with a URL and optional title. You can provide it as a JSON array or JSONL format.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.batch_transcribe.upload_batch_file(
    content_type="jsonl",
    jsonl='{"audio_url": "https://example.com/shiur1.mp3", "title": "Shiur 1"}\n{"audio_url": "https://example.com/shiur2.mp3", "title": "Shiur 2"}',
)

⚙️ Parameters

content_type: BatchFileContentType — Format of your manifest data

json_items: typing.Optional[typing.Sequence[BatchManifestAudioSource]] — For JSON format. Array of audio sources to transcribe (max 500).

jsonl: typing.Optional[str]

For JSONL format. One audio source per line as JSON, separated by newlines (max 500 lines).

Example: {"audio_url": "https://..."}\n{"audio_url": "https://..."}

metadata: typing.Optional[BatchFileMetadata] — Optional title and description for this manifest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch_transcribe.list_batch_files()

📝 Description

List all batch file manifests you've uploaded. Use this to find a batch_file_id for starting a standard mode batch.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.batch_transcribe.list_batch_files()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch_transcribe.get_batch_file(...)

📝 Description

Get details about a specific batch file manifest, including its validation status. Check this after uploading to ensure your manifest is valid before starting a batch.

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.batch_transcribe.get_batch_file(
    batch_file_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

batch_file_id: uuid.UUID — The batch file ID returned from Upload Batch File

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch_transcribe.get_batch_status(...)

📝 Description

Check the progress of a batch transcription. Returns counts of completed, failed, and pending transcriptions, plus details for each individual transcription.

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.batch_transcribe.get_batch_status(
    batch_id=uuid.UUID(
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    ),
)

⚙️ Parameters

batch_id: uuid.UUID — The batch ID returned from Create Batch Transcription

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Categories

client.categories.create_category(...)

📝 Description

Create a new category

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.create_category(
    name="name",
)

⚙️ Parameters

name: str — Name of the category

color_hex: typing.Optional[str] — Hex color code for the category (e.g.,

description: typing.Optional[str] — Optional description to help categorize transcripts.

auto_tag_enabled: typing.Optional[bool] — Whether to automatically tag transcripts that match this category.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.list_categories()

📝 Description

Get all categories for the authenticated user

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.list_categories()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.get_category(...)

📝 Description

Get a specific category by ID

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.get_category(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.update_category(...)

📝 Description

Update an existing category

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.update_category(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category to update

name: typing.Optional[str] — New name for the category

color_hex: typing.Optional[str] — New hex color code for the category (e.g.,

description: typing.Optional[str] — New description for the category

auto_tag_enabled: typing.Optional[bool] — Whether to automatically tag transcripts that match this category

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.delete_category(...)

📝 Description

Delete a category (this will also remove all transcription associations)

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.delete_category(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.add_transcription_to_category(...)

📝 Description

Add a transcription to a category

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.add_transcription_to_category(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category

transcription_id: uuid.UUID — ID of the transcription to add to the category

position: typing.Optional[int] — Optional position within the category for ordering

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.remove_transcription_from_category(...)

📝 Description

Remove a transcription from a category

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.remove_transcription_from_category(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category

transcription_id: uuid.UUID — ID of the transcription to remove

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.get_transcription_categories(...)

📝 Description

Get all categories for a specific transcription

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.get_transcription_categories(
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id: uuid.UUID — ID of the transcription

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.categories.get_category_transcriptions(...)

📝 Description

Get all transcriptions in a specific category

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.categories.get_category_transcriptions(
    category_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

category_id: uuid.UUID — ID of the category

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Health

client.health.get_health()

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.health.get_health()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Link

client.link.extract(...)

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.link.extract(
    url="url",
)

⚙️ Parameters

url: str — URL to extract a downloadable link from. This link must originate from a supported site. You can use the get supported sites endpoint to get a list of supported sites.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.link.get_supported_sites()

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.link.get_supported_sites()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Maishiv

client.maishiv.add_to_knowledge_base(...)

📝 Description

Add a document to the knowledge base.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.maishiv.add_to_knowledge_base(
    document_id="document_id",
)

⚙️ Parameters

document_id: str — ID of the document to add to the knowledge base.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.maishiv.list_knowledge_base_docs()

📝 Description

Get all document IDs currently in the knowledge base.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.maishiv.list_knowledge_base_docs()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.maishiv.remove_from_knowledge_base(...)

📝 Description

Remove a document from the knowledge base.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.maishiv.remove_from_knowledge_base(
    document_id="document_id",
)

⚙️ Parameters

document_id: str — ID of the document to remove from the knowledge base.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Ocr

client.ocr.create_ocr_job(...)

📝 Description

Create an OCR job for a file already uploaded to Supabase Storage.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.ocr.create_ocr_job(
    storage_path="storage_path",
)

⚙️ Parameters

storage_path: str — Path to the uploaded file within the OCR storage bucket.

job_id: typing.Optional[uuid.UUID] — Optional job id. Provide this when you pre-allocate a storage path using the job id.

file_name: typing.Optional[str] — Original file name.

content_type: typing.Optional[str] — MIME type of the uploaded file (e.g., application/pdf, image/png).

file_kind: typing.Optional[str] — Optional hint for file type (pdf or image).

model: typing.Optional[str] — OCR mode to use. "normal" for standard documents, "enhanced" for difficult texts like Rashi script or low quality scans.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.ocr.get_ocr_job(...)

📝 Description

Get OCR job status and extracted text for each page.

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.ocr.get_ocr_job(
    job_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

job_id: uuid.UUID — OCR job id.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Timestamps

client.timestamps.outline(...)

📝 Description

Outline of topics discussed by timestamp, generated end-to-end from a transcription ID.

This endpoint will:

  1. Fetch the transcript and word-level timestamps for the given transcription
  2. Generate chapter topics (title + starting_phrase) using an LLM from the transcript text
  3. Align each topic's starting phrase to timestamps

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.timestamps.outline(
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id: TranscriptionId — ID of the transcription to process end-to-end

monotone: typing.Optional[bool] — If true, each topic is searched after the previous topic's start (with a small backoff)

conclusion_bias: typing.Optional[bool] — If true and a title includes the word "conclusion", search in the last third of the audio

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.timestamps.update_timestamps(...)

📝 Description

Update the timestamps based on edited text.

🔌 Usage

from soferai import SoferAI
from soferai.transcribe import Timestamp

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.timestamps.update_timestamps(
    old_timestamps=[
        Timestamp(
            word="word",
            start=1.1,
            end=1.1,
        ),
        Timestamp(
            word="word",
            start=1.1,
            end=1.1,
        ),
    ],
    edited_text="edited_text",
)

⚙️ Parameters

old_timestamps: typing.Sequence[Timestamp] — The original timestamps associated with the text before editing. These will be used as reference points to align the new timestamps.

edited_text: str — The modified version of the transcription text that needs updated timestamp alignments. This should be the complete text after your edits.

language_to_update: typing.Optional[Language] — If hebrew_word_format included both 'en' and 'he' (and therefor, for the same word there is both an English and a Hebrew version),this specifies which language version of the timestamps to update. Must be either 'en' for English or 'he' for Hebrew timestamps.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Transcribe

client.transcribe.create_transcription(...)

📝 Description

Create a new transcription

🔌 Usage

from soferai import SoferAI
from soferai.transcribe import TranscriptionRequestInfo

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transcribe.create_transcription(
    info=TranscriptionRequestInfo(),
)

⚙️ Parameters

info: TranscriptionRequestInfo — Transcription parameters

audio_url: typing.Optional[str] — URL to a downloadable audio file. Must be a direct link to the file (not a streaming or preview link). If the URL is not directly downloadable, consider using our Link API to extract a downloadable link from supported sites. Either audio_url or audio_file must be provided, but not both.

audio_file: typing.Optional[str]

Base64 encoded audio file content. Either audio_url or audio_file must be provided, but not both.

Base64 Encoding Example

Python:

import base64
from soferai import SoferAI

# Initialize client
client = SoferAI(api_key="your_api_key_here")

# Read and encode audio file
with open("audio.mp3", "rb") as f:
    base64_audio = base64.b64encode(f.read()).decode('utf-8')

# Create transcription request
response = client.transcribe.create_transcription(
    audio_file=base64_audio,
    info={
        "model": "v1",
        "primary_language": "en",
        "hebrew_word_format": ["he"],
        "title": "My Shiur Transcription"
    }
)

print(f"Transcription ID: {response}")

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.transcribe.get_transcription_status(...)

📝 Description

Get transcription status

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transcribe.get_transcription_status(
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id: uuid.UUID — ID of the transcription. Use the ID returned from the Create Transcription endpoint.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.transcribe.get_transcription(...)

📝 Description

Get transcription

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transcribe.get_transcription(
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id: uuid.UUID — ID of the transcription. Use the ID returned from the Create Transcription endpoint.

filter_hebrew_word_format: typing.Optional[str] — Optionally filter the response to a single Hebrew word format. If set to 'en', the response text will have Hebrew characters removed and timestamps will exclude words tagged with 'he'. If set to 'he', italicized transliterations are removed from the text and timestamps will exclude words tagged only with 'en'. If set to 'hybrid', the response includes both transliteration and Hebrew characters for each word.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.transcribe.list_transcriptions()

📝 Description

Get all transcriptions for the authenticated user

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transcribe.list_transcriptions()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Transformations

client.transformations.generate_summary(...)

📝 Description

Generate a Markdown summary for a transcription. If a summary already exists, it is returned.

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transformations.generate_summary(
    transcription_id_=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id_: uuid.UUID — ID of the transcription to summarize

transcription_id: uuid.UUID — ID of the transcription to summarize

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.transformations.get_summary(...)

📝 Description

Get the Markdown summary for a transcription if it exists.

🔌 Usage

import uuid

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.transformations.get_summary(
    transcription_id=uuid.UUID(
        "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
    ),
)

⚙️ Parameters

transcription_id: uuid.UUID — ID of the transcription to fetch summary for

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Utils

client.utils.get_duration(...)

📝 Description

Returns the audio duration in seconds for a provided URL or base64-encoded file.

Provide either audio_url or audio_file (base64). If both are provided, the request is invalid.

🔌 Usage

from soferai import SoferAI

client = SoferAI(
    api_key="YOUR_API_KEY",
)
client.utils.get_duration()

⚙️ Parameters

audio_url: typing.Optional[str] — Direct URL to a downloadable audio file.

audio_file: typing.Optional[str] — Base64-encoded audio file content. Do not include a data URI prefix.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.