martini-client 0.1.0__py3-none-any.whl

martini_client/__init__.py

@@ -0,0 +1,104 @@
+"""The official Python client for the Martini API.
+
+Generate images and video, run saved workflows, and upload reusable media — from a script, a backend, or a
+coding agent — with one API key::
+
+    from martini_client import Martini
+
+    martini = Martini()  # reads MARTINI_API_KEY
+    generation = martini.generations.subscribe(
+        "bytedance/seedance-2.5/text-to-video",
+        input={"prompt": "A moon base at blue hour.", "duration": "auto", "resolution": "720p"},
+    )
+    print(generation.result()["video"]["url"])  # raises GenerationFailedError if it did not complete
+
+Start with ``martini.me()`` to confirm the key, ``martini.models()`` to see what it can call. Everything the
+API answers with a non-2xx status raises a ``MartiniAPIError`` subclass carrying the stable ``code``.
+"""
+
+from . import types
+from ._client import AsyncMartini, Martini
+from ._http import ConfigurationError
+from ._version import API_VERSION, __version__
+from ._wire import WireShapeError
+from .endpoints import ENDPOINTS, EndpointId
+from .errors import (
+    AccessDeniedError,
+    AssetUploadError,
+    AuthenticationError,
+    ConflictError,
+    DraftNotStartedError,
+    GenerationFailedError,
+    GenerationNotSettledError,
+    InsufficientOlivesError,
+    InvalidRequestError,
+    MartiniAPIError,
+    MartiniError,
+    MartiniTimeoutError,
+    MartiniTransportError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    StorageUnavailableError,
+    WorkflowRunFailedError,
+)
+from .resources.assets import UploadFile
+from .types import (
+    Asset,
+    CanvasPosition,
+    Generation,
+    Me,
+    Model,
+    Models,
+    PlacedWorkflow,
+    SavedWorkflow,
+    Workflow,
+    WorkflowList,
+    WorkflowResults,
+    WorkflowRun,
+    WorkflowSettled,
+)
+
+__all__ = [
+    "API_VERSION",
+    "ENDPOINTS",
+    "AccessDeniedError",
+    "Asset",
+    "AssetUploadError",
+    "AsyncMartini",
+    "AuthenticationError",
+    "CanvasPosition",
+    "ConfigurationError",
+    "ConflictError",
+    "DraftNotStartedError",
+    "EndpointId",
+    "Generation",
+    "GenerationFailedError",
+    "GenerationNotSettledError",
+    "InsufficientOlivesError",
+    "InvalidRequestError",
+    "Martini",
+    "MartiniAPIError",
+    "MartiniError",
+    "MartiniTimeoutError",
+    "MartiniTransportError",
+    "Me",
+    "Model",
+    "Models",
+    "NotFoundError",
+    "PlacedWorkflow",
+    "RateLimitError",
+    "SavedWorkflow",
+    "ServerError",
+    "StorageUnavailableError",
+    "UploadFile",
+    "WireShapeError",
+    "Workflow",
+    "WorkflowList",
+    "WorkflowResults",
+    "WorkflowRun",
+    "WorkflowRunFailedError",
+    "WorkflowSettled",
+    "__version__",
+    "types",
+]

martini_client/_client.py

@@ -0,0 +1,191 @@
+"""``Martini`` and ``AsyncMartini``: the two entry points."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._http import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    AsyncTransport,
+    ClientConfig,
+    RequestSpec,
+    SyncTransport,
+    resolve_api_key,
+    resolve_base_url,
+)
+from ._version import API_VERSION
+from .resources.assets import Assets, AsyncAssets
+from .resources.generations import AsyncGenerations, Generations
+from .resources.workflows import AsyncRuns, AsyncWorkflows, Runs, Workflows
+from .types.common import Me
+from .types.models import Models
+
+_ME_SPEC = RequestSpec("GET", "/v1/me", retry=True)
+_MODELS_SPEC = RequestSpec("GET", "/v1/models", retry=True)
+
+
+def _mask(key: str) -> str:
+    return f"{key[:9]}…{key[-4:]}" if len(key) > 16 else "…"
+
+
+def _build_config(
+    api_key: str | None,
+    base_url: str | None,
+    api_version: str,
+    timeout: float,
+    max_retries: int,
+) -> ClientConfig:
+    if max_retries < 0:
+        raise ValueError("max_retries must be 0 or more")
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    return ClientConfig(
+        api_key=resolve_api_key(api_key),
+        base_url=resolve_base_url(base_url),
+        api_version=api_version,
+        timeout=timeout,
+        max_retries=max_retries,
+    )
+
+
+class Martini:
+    """The synchronous Martini client.
+
+    Args:
+        api_key: Your ``mtn_live_…`` key. Defaults to ``MARTINI_API_KEY``. Server-side only — never ship it in a
+            browser bundle or a public config.
+        base_url: Defaults to ``MARTINI_API_URL``, then ``https://api.martini.film``. HTTPS is required except
+            for localhost.
+        api_version: The ``X-Martini-API-Version`` to pin. Defaults to the version this release was built against.
+        timeout: Per-request timeout in seconds.
+        max_retries: Retries for safe requests (GETs, and submits carrying an ``idempotency_key``) on transport
+            errors, 429, and 5xx.
+        http_client: Bring your own ``httpx.Client`` (proxies, custom transports). You own its lifetime.
+
+    Use as a context manager to release the connection pool::
+
+        with Martini() as martini:
+            print(martini.me().organization_name)
+
+    Attributes:
+        generations: ``/v1/generations`` — submit, poll, cancel, start drafts.
+        workflows: ``/v1/workflows`` — list, get, place, and run workflows.
+        runs: ``/v1/runs`` — poll a run and fetch its results.
+        assets: upload reusable media.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_version: str = API_VERSION,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = _build_config(api_key, base_url, api_version, timeout, max_retries)
+        self._transport = SyncTransport(self._config, http_client)
+        self.generations = Generations(self._transport)
+        self.runs = Runs(self._transport)
+        self.workflows = Workflows(self._transport, self.runs)
+        self.assets = Assets(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        """The API origin this client talks to."""
+        return self._config.base_url
+
+    @property
+    def api_version(self) -> str:
+        """The API version this client pins."""
+        return self._config.api_version
+
+    def me(self) -> Me:
+        """``GET /v1/me``: confirm the key works and see which organization it belongs to."""
+        return Me.from_wire(self._transport.request(_ME_SPEC))
+
+    def models(self) -> Models:
+        """``GET /v1/models``: the endpoint aliases this key can invoke, with your organization's pricing."""
+        return Models.from_wire(self._transport.request(_MODELS_SPEC))
+
+    def close(self) -> None:
+        """Release the connection pool (no-op for a caller-supplied ``http_client``)."""
+        self._transport.close()
+
+    def __enter__(self) -> Martini:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Martini(base_url={self._config.base_url!r}, api_key={_mask(self._config.api_key)!r})"
+
+
+class AsyncMartini:
+    """The asynchronous Martini client; same surface as ``Martini`` with ``await``.
+
+    ::
+
+        async with AsyncMartini() as martini:
+            generation = await martini.generations.subscribe("nano-banana-2", input={"prompt": "…"})
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_version: str = API_VERSION,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._config = _build_config(api_key, base_url, api_version, timeout, max_retries)
+        self._transport = AsyncTransport(self._config, http_client)
+        self.generations = AsyncGenerations(self._transport)
+        self.runs = AsyncRuns(self._transport)
+        self.workflows = AsyncWorkflows(self._transport, self.runs)
+        self.assets = AsyncAssets(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        """The API origin this client talks to."""
+        return self._config.base_url
+
+    @property
+    def api_version(self) -> str:
+        """The API version this client pins."""
+        return self._config.api_version
+
+    async def me(self) -> Me:
+        """``GET /v1/me``. See ``me()``."""
+        return Me.from_wire(await self._transport.request(_ME_SPEC))
+
+    async def models(self) -> Models:
+        """``GET /v1/models``. See ``models()``."""
+        return Models.from_wire(await self._transport.request(_MODELS_SPEC))
+
+    async def aclose(self) -> None:
+        """Release the connection pool (no-op for a caller-supplied ``http_client``)."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncMartini:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncMartini(base_url={self._config.base_url!r}, api_key={_mask(self._config.api_key)!r})"
+
+
+__all__ = ["AsyncMartini", "Martini"]

martini_client/_families.py

@@ -0,0 +1,95 @@
+"""Which endpoints share an input shape and an output shape.
+
+This table drives ``scripts/gen_overloads.py``, which writes the ``@overload`` blocks on
+``generations.submit()``/``subscribe()`` so ``input=`` narrows to the right ``TypedDict`` per endpoint.
+``tests/test_overloads_current.py`` fails when the generated blocks are stale, and the backend's drift guard
+keeps ``endpoints.ENDPOINTS`` equal to the handler registry — so a new alias has to be placed in a family
+here (or get a new one) before it ships.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Family:
+    """Endpoints that accept the same input ``TypedDict`` and produce the same output shape."""
+
+    endpoints: tuple[str, ...]
+    input_type: str
+    output_type: str
+
+
+FAMILIES: tuple[Family, ...] = (
+    Family(
+        (
+            "bytedance/seedance-2.0/text-to-video",
+            "bytedance/seedance-2.0/fast/text-to-video",
+            "bytedance/seedance-2.0/mini/text-to-video",
+        ),
+        "Seedance20TextToVideoInput",
+        "VideoOutput",
+    ),
+    Family(
+        (
+            "bytedance/seedance-2.0/image-to-video",
+            "bytedance/seedance-2.0/fast/image-to-video",
+            "bytedance/seedance-2.0/mini/image-to-video",
+        ),
+        "Seedance20ImageToVideoInput",
+        "VideoOutput",
+    ),
+    Family(
+        (
+            "bytedance/seedance-2.0/reference-to-video",
+            "bytedance/seedance-2.0/fast/reference-to-video",
+            "bytedance/seedance-2.0/mini/reference-to-video",
+        ),
+        "Seedance20ReferenceToVideoInput",
+        "VideoOutput",
+    ),
+    Family(("bytedance/seedance-2.5/text-to-video",), "Seedance25TextToVideoInput", "VideoOutput"),
+    Family(("bytedance/seedance-2.5/image-to-video",), "Seedance25ImageToVideoInput", "VideoOutput"),
+    Family(("bytedance/seedance-2.5/reference-to-video",), "Seedance25ReferenceToVideoInput", "VideoOutput"),
+    Family(("xai/grok-imagine-video/v1.5/text-to-video",), "GrokImagine15TextToVideoInput", "VideoOutput"),
+    Family(("xai/grok-imagine-video/v1.5/image-to-video",), "GrokImagine15ImageToVideoInput", "VideoOutput"),
+    Family(
+        ("xai/grok-imagine-video/v1.5/reference-to-video",),
+        "GrokImagine15ReferenceToVideoInput",
+        "VideoOutput",
+    ),
+    Family(("alibaba/wan-3.0/text-to-video",), "Wan3TextToVideoInput", "Wan3Output"),
+    Family(("alibaba/wan-3.0/image-to-video",), "Wan3ImageToVideoInput", "Wan3Output"),
+    Family(("alibaba/wan-3.0/reference-to-video",), "Wan3ReferenceToVideoInput", "Wan3Output"),
+    Family(("alibaba/wan-3.0-prime/text-to-video",), "Wan3PrimeTextToVideoInput", "Wan3Output"),
+    Family(("alibaba/wan-3.0-prime/image-to-video",), "Wan3PrimeImageToVideoInput", "Wan3Output"),
+    Family(("alibaba/wan-3.0-prime/reference-to-video",), "Wan3PrimeReferenceToVideoInput", "Wan3Output"),
+    Family(
+        ("minimax/h3/text-to-video", "fal-ai/minimax/hailuo-03/text-to-video"),
+        "Hailuo03TextToVideoInput",
+        "VideoOutput",
+    ),
+    Family(
+        ("minimax/h3/image-to-video", "fal-ai/minimax/hailuo-03/image-to-video"),
+        "Hailuo03ImageToVideoInput",
+        "VideoOutput",
+    ),
+    Family(
+        ("minimax/h3/reference-to-video", "fal-ai/minimax/hailuo-03/reference-to-video"),
+        "Hailuo03ReferenceToVideoInput",
+        "VideoOutput",
+    ),
+    Family(("minimax/h3-max/text-to-video",), "Hailuo03MaxTextToVideoInput", "VideoOutput"),
+    Family(("minimax/h3-max/image-to-video",), "Hailuo03MaxImageToVideoInput", "VideoOutput"),
+    Family(("minimax/h3-max/reference-to-video",), "Hailuo03MaxReferenceToVideoInput", "VideoOutput"),
+    Family(("minimax/h3-max-turbo/text-to-video",), "Hailuo03MaxTurboTextToVideoInput", "VideoOutput"),
+    Family(("minimax/h3-max-turbo/image-to-video",), "Hailuo03MaxTurboImageToVideoInput", "VideoOutput"),
+    Family(("nano-banana-2", "fal-ai/nano-banana-2"), "NanoBanana2Input", "ImagesOutput"),
+    Family(("nano-banana-2/edit", "fal-ai/nano-banana-2/edit"), "NanoBanana2EditInput", "ImagesOutput"),
+)
+
+
+def family_endpoints() -> set[str]:
+    """Every endpoint covered by a family."""
+    return {endpoint for family in FAMILIES for endpoint in family.endpoints}

martini_client/_http.py

@@ -0,0 +1,280 @@
+"""The HTTP layer shared by the sync and async clients.
+
+Resources describe a call as a ``RequestSpec``; a ``SyncTransport`` or ``AsyncTransport``
+executes it. That is the only place the two clients differ, so behaviour — headers, retries, error mapping —
+is defined exactly once.
+
+Retries: a request is retried only when it is safe to. Every ``GET`` is; a ``POST`` is only when the resource
+marked it (a submit carrying an ``idempotency_key``, which the server dedupes). Retried failures are transport
+errors (DNS, connection, read timeout), ``429``, and ``500``/``502``/``503``/``504``, with exponential backoff
+and jitter, honouring ``Retry-After`` when the server sends one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import sys
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._version import API_VERSION, __version__
+from .errors import MartiniTransportError, api_error_for
+
+DEFAULT_BASE_URL = "https://api.martini.film"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+RETRYABLE_STATUSES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+BACKOFF_INITIAL_SECONDS = 0.5
+BACKOFF_CAP_SECONDS = 8.0
+RETRY_AFTER_CAP_SECONDS = 30.0
+USER_AGENT = (
+    f"martini-client-python/{__version__} python/{sys.version_info.major}.{sys.version_info.minor} "
+    f"httpx/{httpx.__version__}"
+)
+
+
+class ConfigurationError(ValueError):
+    """The client was constructed with a value it cannot use (missing key, non-HTTPS base URL, ...)."""
+
+
+def normalize_base_url(raw: str) -> str:
+    """Validate and normalize the API base URL.
+
+    HTTPS is required except for ``localhost``/``127.0.0.1`` (a local backend). Credentials, a query string,
+    or a fragment are refused rather than silently dropped.
+    """
+    base = raw.strip().rstrip("/")
+    parts = urlsplit(base)
+    if not parts.scheme or not parts.hostname:
+        raise ConfigurationError(f"base_url must be an absolute URL, got {raw!r}")
+    loopback = parts.hostname in ("localhost", "127.0.0.1")
+    if parts.scheme != "https" and not loopback:
+        raise ConfigurationError("base_url must use HTTPS (plain HTTP is allowed only for localhost)")
+    if parts.username or parts.password or parts.query or parts.fragment:
+        raise ConfigurationError("base_url must not include credentials, a query string, or a fragment")
+    return base
+
+
+def resolve_api_key(explicit: str | None) -> str:
+    """The key from the argument or ``MARTINI_API_KEY``; never empty."""
+    key = (explicit if explicit is not None else os.environ.get("MARTINI_API_KEY", "")).strip()
+    if not key:
+        raise ConfigurationError(
+            "No API key. Pass api_key=... or set MARTINI_API_KEY. Create a key under Settings → Martini API."
+        )
+    return key
+
+
+def resolve_base_url(explicit: str | None) -> str:
+    """The base URL from the argument, ``MARTINI_API_URL``, or the production default."""
+    return normalize_base_url(explicit or os.environ.get("MARTINI_API_URL") or DEFAULT_BASE_URL)
+
+
+@dataclass(frozen=True)
+class RequestSpec:
+    """One API call, independent of sync/async execution."""
+
+    method: str
+    path: str
+    json: Any = None
+    params: Mapping[str, str] | None = None
+    retry: bool = False
+    """Whether this request may be repeated after a transport error, 429, or 5xx."""
+    timeout: float | None = None
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Everything a transport needs to talk to one Martini API."""
+
+    api_key: str
+    base_url: str
+    api_version: str = API_VERSION
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+    def headers(self) -> dict[str, str]:
+        """Default request headers."""
+        return {
+            "Authorization": f"Key {self.api_key}",
+            "X-Martini-API-Version": self.api_version,
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Seconds from a ``Retry-After`` header (delta-seconds or an HTTP date), or ``None``."""
+    if not value:
+        return None
+    text = value.strip()
+    if text.isdigit():
+        return float(text)
+    try:
+        when = parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    delta: float = when.timestamp() - time.time()
+    return max(0.0, delta)
+
+
+def backoff_seconds(attempt: int, retry_after: float | None, rng: Callable[[], float] = random.random) -> float:
+    """How long to wait before retry number ``attempt`` (1-based)."""
+    if retry_after is not None:
+        return min(retry_after, RETRY_AFTER_CAP_SECONDS)
+    base = min(BACKOFF_INITIAL_SECONDS * (2.0 ** (attempt - 1)), BACKOFF_CAP_SECONDS)
+    jitter = 0.8 + 0.4 * rng()
+    return base * jitter
+
+
+def read_json(response: httpx.Response) -> dict[str, Any]:
+    """The JSON body as a dict; a non-JSON body becomes ``{"error": <text>}``."""
+    text = response.text
+    if not text:
+        return {}
+    try:
+        parsed = response.json()
+    except ValueError:
+        return {"error": text}
+    return parsed if isinstance(parsed, dict) else {"data": parsed}
+
+
+def raise_for_response(response: httpx.Response) -> dict[str, Any]:
+    """Return the parsed body of a 2xx response; raise the matching ``MartiniAPIError`` otherwise."""
+    body = read_json(response)
+    if response.is_success:
+        return body
+    raise api_error_for(
+        response.status_code,
+        body,
+        retry_after=parse_retry_after(response.headers.get("Retry-After")),
+        fallback_message=f"Martini API request failed (HTTP {response.status_code})",
+    )
+
+
+def _should_retry_status(status: int) -> bool:
+    return status in RETRYABLE_STATUSES
+
+
+def _transport_error(spec: RequestSpec, exc: httpx.TransportError, attempts: int) -> MartiniTransportError:
+    return MartiniTransportError(
+        f"{spec.method} {spec.path} did not get a response after {attempts} attempt(s): {exc.__class__.__name__}"
+    )
+
+
+class SyncTransport:
+    """Executes ``RequestSpec``s over ``httpx.Client``."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        http_client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.config = config
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=config.timeout)
+        # Presigned storage PUTs never ride the caller's client: its auth, default headers, or
+        # base URL would leak to the storage host. This bare client is always ours to close.
+        self._storage = httpx.Client(timeout=config.timeout)
+        self.sleep = sleep
+        """Injected for tests; the client's poll loops and retry backoff wait through this."""
+
+    def request(self, spec: RequestSpec) -> dict[str, Any]:
+        """Run one call, retrying when ``RequestSpec.retry`` allows it; return the parsed 2xx body."""
+        attempts = self.config.max_retries + 1 if spec.retry else 1
+        for attempt in range(1, attempts + 1):
+            try:
+                response = self._client.request(
+                    spec.method,
+                    f"{self.config.base_url}{spec.path}",
+                    json=spec.json,
+                    params=dict(spec.params) if spec.params else None,
+                    headers=self.config.headers(),
+                    timeout=spec.timeout if spec.timeout is not None else self.config.timeout,
+                )
+            except httpx.TransportError as exc:
+                if attempt == attempts:
+                    raise _transport_error(spec, exc, attempts) from exc
+                self.sleep(backoff_seconds(attempt, None))
+                continue
+            if spec.retry and attempt < attempts and _should_retry_status(response.status_code):
+                self.sleep(backoff_seconds(attempt, parse_retry_after(response.headers.get("Retry-After"))))
+                continue
+            return raise_for_response(response)
+        raise AssertionError("unreachable")
+
+    def put_bytes(self, url: str, headers: Mapping[str, str], content: bytes, timeout: float) -> httpx.Response:
+        """PUT raw bytes to a presigned URL. No Martini headers — the URL carries its own authorization."""
+        try:
+            return self._storage.put(url, content=content, headers=dict(headers), timeout=timeout)
+        except httpx.TransportError as exc:
+            raise MartiniTransportError(f"PUT to storage failed: {exc.__class__.__name__}") from exc
+
+    def close(self) -> None:
+        """Close the storage client, and the API client if this transport created it."""
+        self._storage.close()
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport:
+    """Executes ``RequestSpec``s over ``httpx.AsyncClient``."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        http_client: httpx.AsyncClient | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        self.config = config
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=config.timeout)
+        self._storage = httpx.AsyncClient(timeout=config.timeout)
+        self.sleep = sleep
+        """Injected for tests; the client's poll loops and retry backoff wait through this."""
+
+    async def request(self, spec: RequestSpec) -> dict[str, Any]:
+        """Run one call, retrying when ``RequestSpec.retry`` allows it; return the parsed 2xx body."""
+        attempts = self.config.max_retries + 1 if spec.retry else 1
+        for attempt in range(1, attempts + 1):
+            try:
+                response = await self._client.request(
+                    spec.method,
+                    f"{self.config.base_url}{spec.path}",
+                    json=spec.json,
+                    params=dict(spec.params) if spec.params else None,
+                    headers=self.config.headers(),
+                    timeout=spec.timeout if spec.timeout is not None else self.config.timeout,
+                )
+            except httpx.TransportError as exc:
+                if attempt == attempts:
+                    raise _transport_error(spec, exc, attempts) from exc
+                await self.sleep(backoff_seconds(attempt, None))
+                continue
+            if spec.retry and attempt < attempts and _should_retry_status(response.status_code):
+                await self.sleep(backoff_seconds(attempt, parse_retry_after(response.headers.get("Retry-After"))))
+                continue
+            return raise_for_response(response)
+        raise AssertionError("unreachable")
+
+    async def put_bytes(self, url: str, headers: Mapping[str, str], content: bytes, timeout: float) -> httpx.Response:
+        """PUT raw bytes to a presigned URL. No Martini headers — the URL carries its own authorization."""
+        try:
+            return await self._storage.put(url, content=content, headers=dict(headers), timeout=timeout)
+        except httpx.TransportError as exc:
+            raise MartiniTransportError(f"PUT to storage failed: {exc.__class__.__name__}") from exc
+
+    async def aclose(self) -> None:
+        """Close the storage client, and the API client if this transport created it."""
+        await self._storage.aclose()
+        if self._owns_client:
+            await self._client.aclose()