video-to-text-python 1.0.0__tar.gz

video_to_text_python-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.venv
+dist
+.tmp
+build
+*.egg-info
+.pytest_cache
+.ruff_cache
+.mypy_cache
+__pycache__

video_to_text_python-1.0.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: video-to-text-python
+Version: 1.0.0
+Summary: Official Python client for the Video To Text API
+Author: Video To Text
+License: MIT
+Keywords: AI transcription,api,audio to text,audio transcription,speech to text,transcription,video to text,video transcription
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: pydantic<3.0.0,>=2.9.0
+Provides-Extra: dev
+Requires-Dist: mypy<2.0.0,>=1.13.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.10.0,>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# video-to-text-python
+
+Official Python client for the [Video To Text](https://videototext.dev/) API.
+
+- API docs: [Video To Text API](https://docs.videototext.dev)
+- Supports Python 3.10+
+
+## Installation
+
+```bash
+pip install video-to-text-python
+```
+
+## Quick Start
+
+```python
+import os
+from pathlib import Path
+
+from video_to_text import VideoToTextClient
+
+client = VideoToTextClient(api_key=os.environ["VTT_API_KEY"])
+
+task = client.transcriptions.transcribe_file(
+    Path("meeting.mp4"),
+    transcription_mode="balanced",
+)
+
+print(task.status, task.full_text, task.billed_credits)
+```

video_to_text_python-1.0.0/README.md

@@ -0,0 +1,30 @@
+# video-to-text-python
+
+Official Python client for the [Video To Text](https://videototext.dev/) API.
+
+- API docs: [Video To Text API](https://docs.videototext.dev)
+- Supports Python 3.10+
+
+## Installation
+
+```bash
+pip install video-to-text-python
+```
+
+## Quick Start
+
+```python
+import os
+from pathlib import Path
+
+from video_to_text import VideoToTextClient
+
+client = VideoToTextClient(api_key=os.environ["VTT_API_KEY"])
+
+task = client.transcriptions.transcribe_file(
+    Path("meeting.mp4"),
+    transcription_mode="balanced",
+)
+
+print(task.status, task.full_text, task.billed_credits)
+```

video_to_text_python-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "video-to-text-python"
+version = "1.0.0"
+description = "Official Python client for the Video To Text API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Video To Text" }]
+keywords = [
+  "video to text",
+  "audio to text",
+  "AI transcription",
+  "video transcription",
+  "audio transcription",
+  "speech to text",
+  "transcription",
+  "api"
+]
+dependencies = [
+  "httpx>=0.27.0,<1.0.0",
+  "pydantic>=2.9.0,<3.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0,<9.0.0",
+  "ruff>=0.8.0,<0.10.0",
+  "mypy>=1.13.0,<2.0.0"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/video_to_text"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+strict_optional = true

video_to_text_python-1.0.0/src/video_to_text/__init__.py

@@ -0,0 +1,27 @@
+from video_to_text.async_client import AsyncVideoToTextClient
+from video_to_text.client import VideoToTextClient
+from video_to_text.errors import APIError, AuthError, RateLimitError, UploadError, ValidationError
+from video_to_text.types import (
+    TranscriptChunk,
+    TranscriptTask,
+    TranscriptTaskCreateResponse,
+    TranscriptWord,
+    UploadCompleteResponse,
+    UploadCreateResponse,
+)
+
+__all__ = [
+    "APIError",
+    "AsyncVideoToTextClient",
+    "AuthError",
+    "RateLimitError",
+    "TranscriptChunk",
+    "TranscriptTask",
+    "TranscriptTaskCreateResponse",
+    "TranscriptWord",
+    "UploadCompleteResponse",
+    "UploadCreateResponse",
+    "UploadError",
+    "ValidationError",
+    "VideoToTextClient",
+]

video_to_text_python-1.0.0/src/video_to_text/async_client.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import Any
+
+import httpx
+
+from video_to_text.errors import APIError, UploadError, create_api_error
+from video_to_text.resources.tasks import AsyncTasksResource
+from video_to_text.resources.transcriptions import AsyncTranscriptionsResource
+from video_to_text.resources.uploads import AsyncUploadsResource
+
+
+class AsyncVideoToTextClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.videototext.dev",
+        timeout: float = 60,
+        max_retries: int = 2,
+        poll_interval: float = 1.5,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._poll_interval = poll_interval
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            transport=transport,
+        )
+
+        self.uploads = AsyncUploadsResource(self._request, self._put_upload_url)
+        self.tasks = AsyncTasksResource(self._request, self._poll_interval)
+        self.transcriptions = AsyncTranscriptionsResource(self.uploads, self.tasks)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncVideoToTextClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+        skip_retry: bool = False,
+        unwrap_data: bool = True,
+    ) -> Any:
+        attempt = 0
+
+        while True:
+            try:
+                request_headers = {
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Accept": "application/json",
+                    **(headers or {}),
+                }
+                if idempotency_key:
+                    request_headers["Idempotency-Key"] = idempotency_key
+
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    headers=request_headers,
+                )
+                payload = self._parse_json_response(response)
+
+                if response.status_code >= 400:
+                    raise create_api_error(response.status_code, payload)
+
+                if not isinstance(payload, dict) or "data" not in payload or "meta" not in payload:
+                    raise create_api_error(response.status_code, payload)
+
+                if not unwrap_data:
+                    return payload
+
+                return payload["data"]
+            except APIError as error:
+                if skip_retry:
+                    raise
+
+                if not self._should_retry(error.status) or attempt >= self._max_retries:
+                    raise
+
+                await self._sleep_with_backoff(attempt)
+                attempt += 1
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout):
+                if skip_retry or attempt >= self._max_retries:
+                    raise
+                await self._sleep_with_backoff(attempt)
+                attempt += 1
+
+    async def _put_upload_url(self, upload_url: str, content: bytes, mimetype: str) -> None:
+        response = await self._client.request(
+            "PUT",
+            upload_url,
+            content=content,
+            headers={"Content-Type": mimetype},
+        )
+        if response.status_code >= 400:
+            raise UploadError(response.status_code, response.text)
+
+    @staticmethod
+    def _parse_json_response(response: httpx.Response) -> Any:
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError:
+            return {}
+
+    @staticmethod
+    def _should_retry(status: int) -> bool:
+        return status == 429 or status >= 500
+
+    @staticmethod
+    async def _sleep_with_backoff(attempt: int) -> None:
+        base = min(3.0, 0.3 * (2**attempt))
+        jitter = random.random() * 0.1
+        await asyncio.sleep(base + jitter)

video_to_text_python-1.0.0/src/video_to_text/client.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any
+
+import httpx
+
+from video_to_text.errors import APIError, UploadError, create_api_error
+from video_to_text.resources.tasks import TasksResource
+from video_to_text.resources.transcriptions import TranscriptionsResource
+from video_to_text.resources.uploads import UploadsResource
+
+
+class VideoToTextClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.videototext.dev",
+        timeout: float = 60,
+        max_retries: int = 2,
+        poll_interval: float = 1.5,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._poll_interval = poll_interval
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            transport=transport,
+        )
+
+        self.uploads = UploadsResource(self._request, self._put_upload_url)
+        self.tasks = TasksResource(self._request, self._poll_interval)
+        self.transcriptions = TranscriptionsResource(self.uploads, self.tasks)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> VideoToTextClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+        skip_retry: bool = False,
+        unwrap_data: bool = True,
+    ) -> Any:
+        attempt = 0
+
+        while True:
+            try:
+                request_headers = {
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Accept": "application/json",
+                    **(headers or {}),
+                }
+                if idempotency_key:
+                    request_headers["Idempotency-Key"] = idempotency_key
+
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    headers=request_headers,
+                )
+                payload = self._parse_json_response(response)
+
+                if response.status_code >= 400:
+                    raise create_api_error(response.status_code, payload)
+
+                if not isinstance(payload, dict) or "data" not in payload or "meta" not in payload:
+                    raise create_api_error(response.status_code, payload)
+
+                if not unwrap_data:
+                    return payload
+
+                return payload["data"]
+            except APIError as error:
+                if skip_retry:
+                    raise
+
+                if not self._should_retry(error.status) or attempt >= self._max_retries:
+                    raise
+
+                self._sleep_with_backoff(attempt)
+                attempt += 1
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout):
+                if skip_retry or attempt >= self._max_retries:
+                    raise
+                self._sleep_with_backoff(attempt)
+                attempt += 1
+
+    def _put_upload_url(self, upload_url: str, content: bytes, mimetype: str) -> None:
+        response = self._client.request(
+            "PUT",
+            upload_url,
+            content=content,
+            headers={"Content-Type": mimetype},
+        )
+        if response.status_code >= 400:
+            raise UploadError(response.status_code, response.text)
+
+    @staticmethod
+    def _parse_json_response(response: httpx.Response) -> Any:
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError:
+            return {}
+
+    @staticmethod
+    def _should_retry(status: int) -> bool:
+        return status == 429 or status >= 500
+
+    @staticmethod
+    def _sleep_with_backoff(attempt: int) -> None:
+        # Use exponential backoff with light jitter so clients do not retry in lockstep.
+        base = min(3.0, 0.3 * (2**attempt))
+        jitter = random.random() * 0.1
+        time.sleep(base + jitter)

video_to_text_python-1.0.0/src/video_to_text/errors.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Problem:
+    type: str
+    title: str
+    status: int
+    detail: str
+    error_code: str | None = None
+
+
+class APIError(Exception):
+    def __init__(self, problem: Problem):
+        super().__init__(problem.detail)
+        self.problem = problem
+        self.status = problem.status
+        self.type = problem.type
+        self.error_code = problem.error_code
+
+
+class AuthError(APIError):
+    pass
+
+
+class ValidationError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class UploadError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(detail or f"Upload failed with status {status}")
+        self.status = status
+        self.detail = detail
+
+
+def parse_problem(status: int, payload: Any) -> Problem:
+    if isinstance(payload, dict):
+        maybe_type = payload.get("type")
+        maybe_title = payload.get("title")
+        if isinstance(maybe_type, str) and isinstance(maybe_title, str):
+            return Problem(
+                type=maybe_type,
+                title=maybe_title,
+                status=int(payload.get("status") or status),
+                detail=str(payload.get("detail") or maybe_title),
+                error_code=payload.get("errorCode"),
+            )
+
+    return Problem(
+        type="INTERNAL_ERROR",
+        title="Internal server error",
+        status=status,
+        detail="Unexpected API response",
+        error_code="SDK_UNEXPECTED_RESPONSE",
+    )
+
+
+def create_api_error(status: int, payload: Any) -> APIError:
+    problem = parse_problem(status, payload)
+
+    if status in (401, 403):
+        return AuthError(problem)
+    if status in (400, 422):
+        return ValidationError(problem)
+    if status == 429:
+        return RateLimitError(problem)
+
+    return APIError(problem)

video_to_text_python-1.0.0/src/video_to_text/resources/__init__.py

@@ -0,0 +1,15 @@
+from video_to_text.resources.tasks import AsyncTasksResource, TasksResource
+from video_to_text.resources.transcriptions import (
+    AsyncTranscriptionsResource,
+    TranscriptionsResource,
+)
+from video_to_text.resources.uploads import AsyncUploadsResource, UploadsResource
+
+__all__ = [
+    "AsyncTasksResource",
+    "AsyncTranscriptionsResource",
+    "AsyncUploadsResource",
+    "TasksResource",
+    "TranscriptionsResource",
+    "UploadsResource",
+]

video_to_text_python-1.0.0/src/video_to_text/resources/tasks.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import Any
+
+from video_to_text.errors import APIError, Problem
+from video_to_text.types import TranscriptTask, TranscriptTaskCreateResponse
+
+TERMINAL_STATUSES = {"SUCCEEDED", "FAILED", "CANCELED"}
+
+
+class TasksResource:
+    def __init__(self, request: Callable[..., Any], poll_interval: float) -> None:
+        self._request = request
+        self._poll_interval = poll_interval
+
+    def create(
+        self,
+        payload: dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> TranscriptTaskCreateResponse:
+        key = idempotency_key.strip() if idempotency_key else None
+        data = self._request(
+            "POST",
+            "/v1/tasks",
+            json=payload,
+            idempotency_key=key,
+            skip_retry=key is None,
+        )
+        return TranscriptTaskCreateResponse.model_validate(data["task"])
+
+    def get(self, transcript_id: str) -> TranscriptTask:
+        data = self._request("GET", f"/v1/tasks/{transcript_id}")
+        return TranscriptTask.model_validate(data["task"])
+
+    def wait(
+        self,
+        transcript_id: str,
+        *,
+        timeout: float = 600,
+        poll_interval: float | None = None,
+    ) -> TranscriptTask:
+        interval = poll_interval if poll_interval is not None else self._poll_interval
+        started = time.time()
+
+        # Polling only observes server task state; failed terminal states become SDK errors.
+        while True:
+            if time.time() - started > timeout:
+                raise TimeoutError(f"wait timeout after {timeout} seconds")
+
+            task = self.get(transcript_id)
+            if task.status in TERMINAL_STATUSES:
+                if task.status in {"FAILED", "CANCELED"}:
+                    raise APIError(
+                        Problem(
+                            type="TASK_TERMINAL_FAILURE",
+                            title="Task failed",
+                            status=422,
+                            detail=task.show_error or f"Task ended with status {task.status}",
+                            error_code="TASK_TERMINAL_FAILURE",
+                        )
+                    )
+                return task
+
+            time.sleep(interval)
+
+
+class AsyncTasksResource:
+    def __init__(self, request: Callable[..., Any], poll_interval: float) -> None:
+        self._request = request
+        self._poll_interval = poll_interval
+
+    async def create(
+        self,
+        payload: dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> TranscriptTaskCreateResponse:
+        key = idempotency_key.strip() if idempotency_key else None
+        data = await self._request(
+            "POST",
+            "/v1/tasks",
+            json=payload,
+            idempotency_key=key,
+            skip_retry=key is None,
+        )
+        return TranscriptTaskCreateResponse.model_validate(data["task"])
+
+    async def get(self, transcript_id: str) -> TranscriptTask:
+        data = await self._request("GET", f"/v1/tasks/{transcript_id}")
+        return TranscriptTask.model_validate(data["task"])
+
+    async def wait(
+        self,
+        transcript_id: str,
+        *,
+        timeout: float = 600,
+        poll_interval: float | None = None,
+    ) -> TranscriptTask:
+        interval = poll_interval if poll_interval is not None else self._poll_interval
+        loop = asyncio.get_running_loop()
+        started = loop.time()
+
+        while True:
+            if loop.time() - started > timeout:
+                raise TimeoutError(f"wait timeout after {timeout} seconds")
+
+            task = await self.get(transcript_id)
+            if task.status in TERMINAL_STATUSES:
+                if task.status in {"FAILED", "CANCELED"}:
+                    raise APIError(
+                        Problem(
+                            type="TASK_TERMINAL_FAILURE",
+                            title="Task failed",
+                            status=422,
+                            detail=task.show_error or f"Task ended with status {task.status}",
+                            error_code="TASK_TERMINAL_FAILURE",
+                        )
+                    )
+                return task
+
+            await asyncio.sleep(interval)