video-to-text-python 1.0.0__py3-none-any.whl

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/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/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/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/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/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)

video_to_text/resources/transcriptions.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from video_to_text.resources.tasks import AsyncTasksResource, TasksResource
+from video_to_text.resources.uploads import AsyncUploadsResource, UploadInput, UploadsResource
+from video_to_text.types import TranscriptTask, TranscriptTaskCreateResponse
+
+
+def _build_task_payload(
+    asset_id: str,
+    *,
+    language: str | None,
+    timestamp_mode: str | None,
+    transcription_mode: str | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"assetId": asset_id}
+    if language is not None:
+        payload["language"] = language
+    if timestamp_mode is not None:
+        payload["timestampMode"] = timestamp_mode
+    if transcription_mode is not None:
+        payload["transcriptionMode"] = transcription_mode
+    return payload
+
+
+class TranscriptionsResource:
+    def __init__(self, uploads: UploadsResource, tasks: TasksResource) -> None:
+        self._uploads = uploads
+        self._tasks = tasks
+
+    def create_from_file(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+        language: str | None = None,
+        timestamp_mode: str | None = None,
+        transcription_mode: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> TranscriptTaskCreateResponse:
+        asset = self._uploads.upload(
+            content,
+            filename=filename,
+            mimetype=mimetype,
+            file_size=file_size,
+        )
+        return self._tasks.create(
+            _build_task_payload(
+                asset.asset_id,
+                language=language,
+                timestamp_mode=timestamp_mode,
+                transcription_mode=transcription_mode,
+            ),
+            idempotency_key=idempotency_key or str(uuid4()),
+        )
+
+    def transcribe_file(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+        language: str | None = None,
+        timestamp_mode: str | None = None,
+        transcription_mode: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = 600,
+        poll_interval: float | None = None,
+    ) -> TranscriptTask:
+        created = self.create_from_file(
+            content,
+            filename=filename,
+            mimetype=mimetype,
+            file_size=file_size,
+            language=language,
+            timestamp_mode=timestamp_mode,
+            transcription_mode=transcription_mode,
+            idempotency_key=idempotency_key,
+        )
+        return self._tasks.wait(
+            created.transcript_id,
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )
+
+
+class AsyncTranscriptionsResource:
+    def __init__(self, uploads: AsyncUploadsResource, tasks: AsyncTasksResource) -> None:
+        self._uploads = uploads
+        self._tasks = tasks
+
+    async def create_from_file(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+        language: str | None = None,
+        timestamp_mode: str | None = None,
+        transcription_mode: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> TranscriptTaskCreateResponse:
+        asset = await self._uploads.upload(
+            content,
+            filename=filename,
+            mimetype=mimetype,
+            file_size=file_size,
+        )
+        return await self._tasks.create(
+            _build_task_payload(
+                asset.asset_id,
+                language=language,
+                timestamp_mode=timestamp_mode,
+                transcription_mode=transcription_mode,
+            ),
+            idempotency_key=idempotency_key or str(uuid4()),
+        )
+
+    async def transcribe_file(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+        language: str | None = None,
+        timestamp_mode: str | None = None,
+        transcription_mode: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = 600,
+        poll_interval: float | None = None,
+    ) -> TranscriptTask:
+        created = await self.create_from_file(
+            content,
+            filename=filename,
+            mimetype=mimetype,
+            file_size=file_size,
+            language=language,
+            timestamp_mode=timestamp_mode,
+            transcription_mode=transcription_mode,
+            idempotency_key=idempotency_key,
+        )
+        return await self._tasks.wait(
+            created.transcript_id,
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )

video_to_text/resources/uploads.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from video_to_text.types import UploadCompleteResponse, UploadCreateResponse
+
+BytesLike = bytes | bytearray | memoryview
+UploadInput = BytesLike | str | os.PathLike[str]
+
+
+def _normalize_upload_input(
+    content: UploadInput,
+    *,
+    filename: str | None,
+    mimetype: str | None,
+    file_size: int | None,
+) -> tuple[bytes, str, str, int]:
+    resolved_filename: str | None
+    resolved_mimetype: str | None
+    if isinstance(content, str | os.PathLike):
+        path = Path(content)
+        body = path.read_bytes()
+        resolved_filename = filename or path.name
+        resolved_mimetype = mimetype or mimetypes.guess_type(str(path))[0]
+        resolved_size = file_size if file_size is not None else path.stat().st_size
+    else:
+        body = content.tobytes() if isinstance(content, memoryview) else bytes(content)
+        resolved_filename = filename
+        resolved_mimetype = mimetype
+        resolved_size = file_size if file_size is not None else len(body)
+
+    if not resolved_filename:
+        raise ValueError("filename is required for bytes-like upload content")
+    if not resolved_mimetype:
+        raise ValueError("mimetype is required for bytes-like upload content")
+    if resolved_size < 0:
+        raise ValueError("file_size must be non-negative")
+
+    return body, resolved_filename, resolved_mimetype, int(resolved_size)
+
+
+async def _normalize_upload_input_async(
+    content: UploadInput,
+    *,
+    filename: str | None,
+    mimetype: str | None,
+    file_size: int | None,
+) -> tuple[bytes, str, str, int]:
+    if isinstance(content, str | os.PathLike):
+        path = Path(content)
+        body = await asyncio.to_thread(path.read_bytes)
+        resolved_filename = filename or path.name
+        resolved_mimetype = mimetype or mimetypes.guess_type(str(path))[0]
+        resolved_size = file_size if file_size is not None else path.stat().st_size
+        if not resolved_filename:
+            raise ValueError("filename is required for bytes-like upload content")
+        if not resolved_mimetype:
+            raise ValueError("mimetype is required for bytes-like upload content")
+        if resolved_size < 0:
+            raise ValueError("file_size must be non-negative")
+        return body, resolved_filename, resolved_mimetype, int(resolved_size)
+
+    return _normalize_upload_input(
+        content,
+        filename=filename,
+        mimetype=mimetype,
+        file_size=file_size,
+    )
+
+
+class UploadsResource:
+    def __init__(self, request: Callable[..., Any], put_upload_url: Callable[..., Any]) -> None:
+        self._request = request
+        self._put_upload_url = put_upload_url
+
+    def create(self, payload: dict[str, Any]) -> UploadCreateResponse:
+        data = self._request(
+            "POST",
+            "/v1/uploads",
+            json=payload,
+            skip_retry=True,
+        )
+        return UploadCreateResponse.model_validate(data)
+
+    def put(self, upload_url: str, content: BytesLike, *, mimetype: str) -> None:
+        body = content.tobytes() if isinstance(content, memoryview) else bytes(content)
+        self._put_upload_url(upload_url, body, mimetype)
+
+    def complete(self, upload_id: str, payload: dict[str, Any]) -> UploadCompleteResponse:
+        data = self._request(
+            "POST",
+            f"/v1/uploads/{upload_id}/operations/complete",
+            json=payload,
+            skip_retry=True,
+        )
+        return UploadCompleteResponse.model_validate(data)
+
+    def upload(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+    ) -> UploadCompleteResponse:
+        body, resolved_filename, resolved_mimetype, resolved_size = _normalize_upload_input(
+            content,
+            filename=filename,
+            mimetype=mimetype,
+            file_size=file_size,
+        )
+        upload = self.create(
+            {
+                "filename": resolved_filename,
+                "mimetype": resolved_mimetype,
+            }
+        )
+        self.put(upload.upload_url, body, mimetype=resolved_mimetype)
+        return self.complete(
+            upload.upload_id,
+            {
+                "fileKey": upload.file_key,
+                "fileUrl": upload.file_url,
+                "filename": resolved_filename,
+                "mimetype": resolved_mimetype,
+                "fileSize": resolved_size,
+            },
+        )
+
+
+class AsyncUploadsResource:
+    def __init__(self, request: Callable[..., Any], put_upload_url: Callable[..., Any]) -> None:
+        self._request = request
+        self._put_upload_url = put_upload_url
+
+    async def create(self, payload: dict[str, Any]) -> UploadCreateResponse:
+        data = await self._request(
+            "POST",
+            "/v1/uploads",
+            json=payload,
+            skip_retry=True,
+        )
+        return UploadCreateResponse.model_validate(data)
+
+    async def put(self, upload_url: str, content: BytesLike, *, mimetype: str) -> None:
+        body = content.tobytes() if isinstance(content, memoryview) else bytes(content)
+        await self._put_upload_url(upload_url, body, mimetype)
+
+    async def complete(self, upload_id: str, payload: dict[str, Any]) -> UploadCompleteResponse:
+        data = await self._request(
+            "POST",
+            f"/v1/uploads/{upload_id}/operations/complete",
+            json=payload,
+            skip_retry=True,
+        )
+        return UploadCompleteResponse.model_validate(data)
+
+    async def upload(
+        self,
+        content: UploadInput,
+        *,
+        filename: str | None = None,
+        mimetype: str | None = None,
+        file_size: int | None = None,
+    ) -> UploadCompleteResponse:
+        body, resolved_filename, resolved_mimetype, resolved_size = (
+            await _normalize_upload_input_async(
+                content,
+                filename=filename,
+                mimetype=mimetype,
+                file_size=file_size,
+            )
+        )
+        upload = await self.create(
+            {
+                "filename": resolved_filename,
+                "mimetype": resolved_mimetype,
+            }
+        )
+        await self.put(upload.upload_url, body, mimetype=resolved_mimetype)
+        return await self.complete(
+            upload.upload_id,
+            {
+                "fileKey": upload.file_key,
+                "fileUrl": upload.file_url,
+                "filename": resolved_filename,
+                "mimetype": resolved_mimetype,
+                "fileSize": resolved_size,
+            },
+        )

video_to_text/types.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+TaskStatus = Literal["QUEUED", "PROCESSING", "SUCCEEDED", "FAILED", "CANCELED"]
+TimestampMode = Literal["CHUNK", "WORD"]
+TranscriptionMode = Literal["balanced", "precision"]
+
+
+class ApiModel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class UploadCreateResponse(ApiModel):
+    upload_url: str = Field(alias="uploadUrl")
+    file_key: str = Field(alias="fileKey")
+    file_url: str = Field(alias="fileUrl")
+    upload_id: str = Field(alias="uploadId")
+    expires_at: str = Field(alias="expiresAt")
+
+
+class UploadCompleteResponse(ApiModel):
+    asset_id: str = Field(alias="assetId")
+
+
+class TranscriptChunk(ApiModel):
+    seq: int
+    start_ms: int = Field(alias="startMs")
+    end_ms: int = Field(alias="endMs")
+    text: str
+    speaker_key: str | None = Field(default=None, alias="speakerKey")
+    speaker_name: str | None = Field(default=None, alias="speakerName")
+    word_start_index: int | None = Field(default=None, alias="wordStartIndex")
+    word_end_index: int | None = Field(default=None, alias="wordEndIndex")
+
+
+class TranscriptWord(ApiModel):
+    text: str
+    start_ms: int = Field(alias="startMs")
+    end_ms: int = Field(alias="endMs")
+    speaker_key: str | None = Field(default=None, alias="speakerKey")
+
+
+class TranscriptTaskCreateResponse(ApiModel):
+    transcript_id: str = Field(alias="transcriptId")
+    status: TaskStatus
+    language: str
+    timestamp_mode: TimestampMode = Field(alias="timestampMode")
+    transcription_mode: TranscriptionMode = Field(alias="transcriptionMode")
+    billed_credits: str = Field(alias="billedCredits")
+
+
+class TranscriptTask(ApiModel):
+    transcript_id: str = Field(alias="transcriptId")
+    status: TaskStatus
+    show_error: str | None = Field(alias="showError")
+    full_text: str = Field(alias="fullText")
+    chunks: list[TranscriptChunk]
+    words: list[TranscriptWord]
+    source_duration_ms: int = Field(alias="sourceDurationMs")
+    language: str
+    result_language: str | None = Field(alias="resultLanguage")
+    timestamp_mode: TimestampMode = Field(alias="timestampMode")
+    transcription_mode: TranscriptionMode = Field(alias="transcriptionMode")
+    billed_credits: str = Field(alias="billedCredits")
+    created_at: str = Field(alias="createdAt")

video_to_text_python-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+video_to_text/__init__.py,sha256=aZXMnkhjSUfdt2P3vuY1QX8j6TkyTCPYn-yQLimawaw,725
+video_to_text/async_client.py,sha256=wsn-ZkObMGFocwUwOSukbru9n0yTCq1-voqlvDd5uUo,4435
+video_to_text/client.py,sha256=6CrLnCSdwootbSvettEpH7H_rqsq01FFfjFJ8c2s14I,4385
+video_to_text/errors.py,sha256=gG-Vl8F1A71kFs1wi-UCAkCEC__HEs8v30nKbe0NZYQ,1893
+video_to_text/types.py,sha256=igSI0hAmOFiLdu0JC2LxHiJvD1_1yGQy-8_OGVKp3oM,2363
+video_to_text/resources/__init__.py,sha256=vbN4o2PcfpLgXik_erwv_5BAZ2xBCmRiRZZm-3l2oRw,452
+video_to_text/resources/tasks.py,sha256=FUizcfZdf0HDhT25sGXYinve-IACOgrQOQy4abaggbA,4310
+video_to_text/resources/transcriptions.py,sha256=2Z7Id9VnLY0PvEX804HogNOFUx3n0s4MoAv4HaZE_G8,4893
+video_to_text/resources/uploads.py,sha256=hIfWK3ZEx3W2RuyArif7-j6tPM-9DrY_HyDpQn33d-8,6755
+video_to_text_python-1.0.0.dist-info/METADATA,sha256=ZkPCGtaId_rRPU4Yo81oQQJEQHMhytDIpMq9xlT8qng,1190
+video_to_text_python-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+video_to_text_python-1.0.0.dist-info/RECORD,,

video_to_text_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any