relaygpu-client 0.1.0__py3-none-any.whl

relaygpu/_async/files.py

@@ -0,0 +1,293 @@
+"""``POST|GET|DELETE /v2/files`` and the implicit upload (port of src/files.ts). Hand-written async;
+``_sync/files.py`` is generated from it by scripts/unasync.py. The pure rules live in ``relaygpu/inputs.py``."""
+
+from __future__ import annotations
+
+import base64
+import os
+from collections.abc import AsyncIterator, Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from .._core import ReplayableBody
+from .._util import path_id
+from ..inputs import (
+    CHUNK_SIZE,
+    HEAD,
+    INLINE_IMAGE_MAX_BYTES,
+    UPLOAD_TYPE_ERROR,
+    FileData,
+    as_chunk,
+    async_read,
+    collect_files,
+    contains_file,
+    file_name_of,
+    is_async_iterator,
+    is_bytes_like,
+    is_file_data,
+    is_stream,
+    size_of,
+    sniff_media_type,
+    substitute,
+    unknown_type_error,
+)
+from ..types import FileListResponse, FileObject, Retention, UploadOptions
+
+if TYPE_CHECKING:
+    from .._core import RawBody
+    from .client import AsyncRelay
+
+__all__ = ["INLINE_IMAGE_MAX_BYTES", "AsyncFiles"]
+
+
+def _path(file_id: str) -> str:
+    return f"/v2/files/{path_id(file_id)}"
+
+
+def _refuse_foreign_stream(data: object) -> None:
+    """The async client reads every stream. Its generated sync twin reads ``isinstance(data, Iterator)`` here, so an
+    async iterator handed to ``Relay`` is refused before anything is sent."""
+    if is_async_iterator(data) and not isinstance(data, AsyncIterator):
+        raise TypeError("Relay: the sync client cannot read an async iterator; pass an iterator of bytes, or use the async client")
+
+
+async def _chunks(data: Any) -> AsyncIterator[bytes]:
+    """Every byte of a path, a file object or an iterator, in chunks; never the whole file in memory."""
+    if isinstance(data, os.PathLike):
+        with open(data, "rb") as f:
+            while chunk := await async_read(f, CHUNK_SIZE):
+                yield chunk
+    elif callable(getattr(data, "read", None)):
+        while chunk := await async_read(data, CHUNK_SIZE):
+            yield chunk
+    elif isinstance(data, AsyncIterator):
+        async for c in data:
+            yield as_chunk(c)
+    else:
+        for c in data:
+            yield as_chunk(c)
+
+
+class _PathBody(ReplayableBody):
+    """A path's bytes as a request body that re-opens the file on each iteration, so the transport may resend it."""
+
+    def __init__(self, path: os.PathLike[str]) -> None:
+        self._path = path
+
+    def __aiter__(self) -> AsyncIterator[bytes]:
+        return _chunks(self._path)
+
+
+async def _peek(src: AsyncIterator[bytes], n: int) -> tuple[bytes, AsyncIterator[bytes]]:
+    """Reads at least ``n`` bytes (or to the end) and returns them plus an iterator that replays everything."""
+    chunks: list[bytes] = []
+    have = 0
+    while have < n:
+        try:
+            c = await src.__anext__()
+        except StopAsyncIteration:
+            break
+        chunks.append(c)
+        have += len(c)
+
+    async def replay() -> AsyncIterator[bytes]:
+        for c in chunks:
+            yield c
+        async for c in src:
+            yield c
+
+    return b"".join(chunks)[:n], replay()
+
+
+def _media_type_of(data: Any) -> str | None:
+    """The type sniffed from the first bytes of bytes or a path (never a stream: it can be read once)."""
+    if is_bytes_like(data):
+        return sniff_media_type(bytes(data[:HEAD]))
+    if isinstance(data, os.PathLike):
+        with open(data, "rb") as f:
+            return sniff_media_type(f.read(HEAD))
+    return None
+
+
+async def _resolve(data: Any, explicit: str | None) -> tuple[RawBody, str | None]:
+    """The request body and media type (``explicit`` → sniffed magic bytes) without consuming the data: a path is
+    re-opened to stream, a file object or an iterator is peeked and handed back whole."""
+    if is_bytes_like(data):
+        return bytes(data), explicit or _media_type_of(data)
+    if isinstance(data, os.PathLike):
+        return _PathBody(data), explicit or _media_type_of(data)
+    stream = _chunks(data)
+    if explicit:
+        return stream, explicit
+    head, replay = await _peek(stream, HEAD)
+    return replay, sniff_media_type(head)
+
+
+async def _inline(data: Any, data_uri: bool, key: str) -> str:
+    """The file as raw base64, or as a data URI typed from its first bytes. Reads the data once."""
+    if data_uri and is_stream(data):
+        raise unknown_type_error(f'field "{key}"')  # a stream is never sniffed: it can be read once
+    buf = bytes(data) if is_bytes_like(data) else b"".join([c async for c in _chunks(data)])
+    b64 = base64.b64encode(buf).decode("ascii")
+    if not data_uri:
+        return b64
+    media_type = sniff_media_type(buf[:HEAD])
+    if not media_type:
+        raise unknown_type_error(f'field "{key}"')
+    return f"data:{media_type};base64,{b64}"
+
+
+class AsyncFiles:
+    """``POST|GET|DELETE /v2/files``: host an image, video or audio file and get a link any ``*_url`` field takes."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def upload(
+        self,
+        data: FileData | str,
+        *,
+        retention: Retention | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> FileObject:
+        """Uploads the raw bytes and returns the hosted file (``url`` is the link).
+
+        ``data``: bytes, a path (``pathlib.Path`` or ``str``), a binary file object, or an iterator of bytes (the
+        async client also takes an async iterator). Paths and file objects are streamed in chunks; a path, a file
+        object or an iterator is sent once, never retried. ``content_type`` defaults to the type sniffed from the first bytes;
+        ``filename`` to the path's / file object's name; ``retention`` to ``relay1h`` (server-side).
+        """
+        if isinstance(data, str):
+            data = Path(data)
+        if not is_file_data(data):
+            raise TypeError(UPLOAD_TYPE_ERROR)
+        _refuse_foreign_stream(data)
+        body, media_type = await _resolve(data, content_type)
+        if not media_type:
+            raise unknown_type_error("the upload")
+        # A path's size is known, so it rides as Content-Length (as a Blob's does) instead of a chunked body.
+        size = size_of(data) if isinstance(data, os.PathLike) else None
+        res = await self._relay._http.request(
+            "POST",
+            "/v2/files",
+            content=body,
+            content_type=media_type,
+            headers={"Content-Length": str(size)} if size is not None else None,
+            query={"retention": retention, "filename": filename if filename is not None else file_name_of(data)},
+            idempotency_key=idempotency_key,
+        )
+        return cast(FileObject, res.data)
+
+    async def copy(
+        self,
+        url: str,
+        *,
+        retention: Retention | None = None,
+        filename: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> FileObject:
+        """Has Relay copy a public http(s) object (the JSON form; ``retention`` / ``filename`` ride in the body)."""
+        body: dict[str, str] = {"url": url}
+        if retention is not None:
+            body["retention"] = retention
+        if filename is not None:
+            body["filename"] = filename
+        res = await self._relay._http.request("POST", "/v2/files", json=body, idempotency_key=idempotency_key)
+        return cast(FileObject, res.data)
+
+    async def get(self, file_id: str) -> FileObject:
+        """One file. Unknown, foreign or long-expired ids raise ``FileNotFoundError`` (``relaygpu.errors``)."""
+        res = await self._relay._http.request("GET", _path(file_id))
+        return cast(FileObject, res.data)
+
+    async def list(
+        self,
+        *,
+        source: Literal["upload", "result"] | None = None,
+        status: Literal["ready", "expired"] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> FileListResponse:
+        """One page, newest first: uploads and hosted results. Follow ``next_cursor`` (``None`` on the last page).
+        ``limit`` is 1–200, default 50."""
+        query = {"source": source, "status": status, "limit": limit, "cursor": cursor}
+        res = await self._relay._http.request("GET", "/v2/files", query=query)
+        return cast(FileListResponse, res.data)
+
+    async def list_all(
+        self,
+        *,
+        source: Literal["upload", "result"] | None = None,
+        status: Literal["ready", "expired"] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> AsyncIterator[FileObject]:
+        """Every file across pages, following ``next_cursor``."""
+        while True:
+            page = await self.list(source=source, status=status, limit=limit, cursor=cursor)
+            files = page["files"]
+            for f in files:
+                yield f
+            nxt = page.get("next_cursor")
+            if not nxt or not files or nxt == cursor:
+                return
+            cursor = nxt
+
+    async def delete(self, file_id: str) -> None:
+        """Takes the link down now (idempotent; no refund)."""
+        await self._relay._http.request("DELETE", _path(file_id))
+
+    async def prepare_inputs(
+        self,
+        input: Mapping[str, Any],
+        *,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+        request_schema: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """The implicit upload: a copy of ``input`` with every file in a ``*_url`` / ``*_urls`` field (nested too)
+        uploaded and replaced by its link, or — per the route's request schema — inlined as base64:
+
+        - a ``*_url`` / ``*_urls`` field, or a field whose schema says it takes a URL → uploaded, replaced by its link;
+        - with ``inline_images``, an image ≤ 4 MB (bytes or a path) in a field whose schema says it takes base64 →
+          inlined (a data URI for URL-shaped fields and fields that name data URIs, raw base64 otherwise);
+        - a field that takes base64 only (no URL) → always inlined, whatever the size;
+        - anything else → ``TypeError``, before the first upload.
+
+        A ``str`` is never file data here (it is the URL or base64 the caller wrote). One upload per distinct file
+        object (identity) per call. A body without files makes no calls.
+        """
+        if not contains_file(input):
+            return dict(input)
+        found = collect_files(input, request_schema)  # refuses a misplaced file before the first upload
+        for data, _f, _r in found:
+            _refuse_foreign_stream(data)
+        chosen = (upload or {}).get("retention")
+        retention = chosen if chosen is not None else "relay1h"
+        done: dict[tuple[int, str], str] = {}  # one upload / encoding per distinct object and form
+        keep: list[object] = []  # holds each object so its id() is not reused during the call
+        out: list[str] = []
+        for data, f, rule in found:
+            if not rule.base64:
+                inline = False
+            elif not rule.url:
+                inline = True  # base64-only: inlining is the only way in, whatever the size (a stream is read into memory)
+            else:
+                size = size_of(data)  # None for a stream: never inlined
+                inline = (
+                    inline_images
+                    and size is not None
+                    and size <= INLINE_IMAGE_MAX_BYTES
+                    and (_media_type_of(data) or "").startswith("image/")
+                )
+            key = (id(data), ("uri" if rule.data_uri else "raw") if inline else "upload")
+            if key not in done:
+                keep.append(data)
+                if inline:
+                    done[key] = await _inline(data, rule.data_uri, f.key)
+                else:
+                    done[key] = (await self.upload(data, retention=retention, filename=file_name_of(data)))["url"]
+            out.append(done[key])
+        return cast("dict[str, Any]", substitute(input, iter(out)))

relaygpu/_async/image.py

@@ -0,0 +1,157 @@
+"""Image generation and editing (port of src/image.ts). The parsing lives in ``relaygpu/_images.py``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from .. import _clock
+from .._images import decode_b64, image_values, parse_image_value
+from ..types import KnownImageModel, Mode, TaskProgress, UploadOptions
+from ._http import AsyncHttpClient
+from .run import run
+
+if TYPE_CHECKING:
+    from .client import AsyncRelay
+
+__all__ = ["AsyncImageResult", "AsyncImages", "AsyncRelayImage", "normalise_images", "to_relay_image"]
+
+
+@dataclass(frozen=True, repr=False)
+class AsyncRelayImage:
+    """One output image, URL- or base64-backed. URLs expire (1 h by default; ``store_output`` buys 1/7/30 d)."""
+
+    url: str | None = None
+    b64: str | None = None
+    """Raw base64 (no ``data:`` prefix)."""
+    mime_type: str | None = None
+
+    _transport: ClassVar[AsyncHttpClient | None] = None
+    """The client's transport (set on the images ``images.generate`` / ``edit`` return; never a dataclass field)."""
+
+    def __getstate__(self) -> dict[str, Any]:
+        """Pickle / copy without the transport (such a copy downloads over a fresh client)."""
+        return {k: v for k, v in self.__dict__.items() if k != "_transport"}
+
+    def __repr__(self) -> str:
+        if self.url is not None:
+            return f"{type(self).__name__}(url={self.url!r})"
+        return f"{type(self).__name__}(b64=<{len(self.b64 or '')} chars>, mime_type={self.mime_type!r})"
+
+    async def to_bytes(self) -> bytes:
+        """Downloads (URL; no Relay credential is sent) or decodes (base64) the bytes. An image ``images.generate`` /
+        ``edit`` returned downloads over that client's HTTP transport; one built by ``to_relay_image`` over a fresh one."""
+        if self.url is None:
+            return decode_b64(self.b64 or "")
+        if self._transport is not None:
+            return await self._transport.download(self.url)
+        transport = AsyncHttpClient()
+        try:
+            return await transport.download(self.url)
+        finally:
+            await transport.aclose()
+
+    async def save(self, path: str | Path) -> None:
+        """Writes the bytes to a file."""
+        await _clock.async_write_bytes(path, await self.to_bytes())
+
+
+@dataclass(frozen=True)
+class AsyncImageResult:
+    """``images``: every output image, normalised. ``raw``: the response body (or the async task's ``result``) exactly
+    as the API sent it."""
+
+    images: list[AsyncRelayImage] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+def to_relay_image(value: str, mime_hint: str | None = None) -> AsyncRelayImage:
+    """Builds a ``RelayImage`` from a URL, a data URI or a bare base64 string."""
+    url, b64, mime = parse_image_value(value, mime_hint)
+    return AsyncRelayImage(url=url, b64=b64, mime_type=mime)
+
+
+def normalise_images(body: Mapping[str, Any], input: Mapping[str, Any] | None = None) -> list[AsyncRelayImage]:
+    """Normalises every image response shape the live routes use: ``urls[]``, ``images[]`` (base64 or links),
+    OpenAI-style ``data[]``, single ``url`` / ``image``."""
+    values, hint = image_values(body, input)
+    return [to_relay_image(v, hint) for v in values]
+
+
+class AsyncImages:
+    """Image generation and editing. Both methods take any image model; the route comes from ``relay.models.get``."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def generate(
+        self,
+        model: KnownImageModel | str,
+        input: Mapping[str, Any],
+        *,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> AsyncImageResult:
+        """Generates images. Returns ``ImageResult(images, raw)`` with every image normalised to a ``RelayImage`` (URL or
+        base64). If the route answers async (``async_=True``), waits for the task like ``run()`` does; ``timeout`` is
+        that wait's budget (default 20 min) and the per-attempt HTTP timeout of a sync call."""
+        raw = await run(
+            self._relay,
+            model,
+            input,
+            wait=True,
+            on_progress=on_progress,
+            timeout=timeout,
+            mode=mode,
+            store_output=store_output,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            async_=async_,
+            upload=upload,
+            inline_images=inline_images,
+        )
+        body = cast("dict[str, Any]", raw)  # wait=True: never the 202 envelope
+        images = normalise_images(body, input)
+        for img in images:
+            object.__setattr__(img, "_transport", self._relay._http)  # frozen; a ClassVar, so no field changes
+        return AsyncImageResult(images=images, raw=body)
+
+    async def edit(
+        self,
+        model: KnownImageModel | str,
+        input: Mapping[str, Any],
+        *,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> AsyncImageResult:
+        """Image-to-image editing (``image`` / ``images`` / ``*_url`` inputs; file values are uploaded). Same contract
+        as ``generate``."""
+        return await self.generate(
+            model,
+            input,
+            on_progress=on_progress,
+            timeout=timeout,
+            mode=mode,
+            store_output=store_output,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            async_=async_,
+            upload=upload,
+            inline_images=inline_images,
+        )

relaygpu/_async/keys.py

@@ -0,0 +1,103 @@
+"""The ``keys`` namespace (port of src/keys.ts)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any, cast
+
+from .._core import _UNSET
+from .._generated.error_codes import KeyNotFoundError
+from .._generated.types import (
+    CreateKeyRequest,
+    CreateKeyResponse,
+    KeyBudgetTopupResponse,
+    KeyListResponse,
+    KeyResponse,
+    PromoteKeyResponse,
+    UpdateKeyRequest,
+)
+from .._shapes import KeyListAllParams, KeyListParams
+from .._util import path_id
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .client import AsyncRelay
+
+KeyMutationResult = dict[str, Any]
+"""The spec leaves these bodies untyped."""
+
+
+def _key_path(key_id: str) -> str:
+    return f"/v2/customer/keys/{path_id(key_id)}"
+
+
+class AsyncKeys:
+    """API key management. Auth: a dashboard JWT, or a partner superkey (custom tiers); anything else gets the server's
+    403. Address keys by ``key_id``, never by secret (a secret in a path answers 400)."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def _call(self, method: str, path: str, body: Any = _UNSET) -> Any:
+        return (await self._relay._http.request(method, path, json=body)).data
+
+    async def list(self, **params: Unpack[KeyListParams]) -> KeyListResponse:
+        """``GET /v2/customer/keys``: newest first, secrets masked. Page with ``starting_after`` = ``next_cursor``."""
+        res = await self._relay._http.request("GET", "/v2/customer/keys", query=params)
+        return cast(KeyListResponse, res.data)
+
+    async def list_all(self, **params: Unpack[KeyListAllParams]) -> AsyncIterator[KeyResponse]:
+        """Every key matching the filters, following ``next_cursor`` across pages."""
+        cursor: str | None = None
+        while True:
+            query: KeyListParams = {**params, "starting_after": cursor}
+            page = await self.list(**query)
+            for k in page["keys"]:
+                yield k
+            nxt = page.get("next_cursor")
+            if not page["has_more"] or not nxt:
+                return
+            cursor = nxt
+
+    async def create(self, **fields: Unpack[CreateKeyRequest]) -> CreateKeyResponse:
+        """``POST /v2/customer/keys``. The response's ``key`` is the full secret and is returned **only here**, once; store it
+        now (every later response masks it). The first key on a custom tier becomes the superkey (``is_superkey: True``).
+        ``key_budget`` is custom-tier only (403 otherwise). Never retried (a retry could mint twice)."""
+        return cast(CreateKeyResponse, await self._call("POST", "/v2/customer/keys", dict(fields)))
+
+    async def get(self, key_id: str) -> KeyResponse:
+        """One key by ``key_id``. The API has no get-one route, so this pages ``GET /v2/customer/keys`` and matches
+        ``key_id``; absent → ``KeyNotFoundError`` (code ``KEY_NOT_FOUND``, raised client-side, ``status`` None)."""
+        async for k in self.list_all(limit=1000):
+            if k.get("key_id") == key_id:
+                return k
+        raise KeyNotFoundError(f"Key not found: {key_id}", code="KEY_NOT_FOUND")
+
+    async def update(self, key_id: str, **patch: Unpack[UpdateKeyRequest]) -> KeyMutationResult:
+        """``PATCH /v2/customer/keys/{key_id}``: send only what changes; ``restrictions`` is replaced, not merged."""
+        return cast(KeyMutationResult, await self._call("PATCH", _key_path(key_id), dict(patch)))
+
+    async def rename(self, key_id: str, name: str) -> KeyMutationResult:
+        """Renames a key (names are unique per customer; 400 on duplicate)."""
+        return await self.update(key_id, name=name)
+
+    async def revoke(self, key_id: str) -> KeyMutationResult:
+        """``POST …/revoke``. Reversible with :meth:`unrevoke`."""
+        return cast(KeyMutationResult, await self._call("POST", f"{_key_path(key_id)}/revoke"))
+
+    async def unrevoke(self, key_id: str) -> KeyMutationResult:
+        """``POST …/unrevoke``."""
+        return cast(KeyMutationResult, await self._call("POST", f"{_key_path(key_id)}/unrevoke"))
+
+    async def delete(self, key_id: str) -> KeyMutationResult:
+        """``DELETE /v2/customer/keys/{key_id}``: permanent; the key must be revoked first."""
+        return cast(KeyMutationResult, await self._call("DELETE", _key_path(key_id)))
+
+    async def topup(self, key_id: str, amount: float) -> KeyBudgetTopupResponse:
+        """``POST …/topup``: atomically adds ``amount`` USD to the key's ``key_budget`` (custom tiers; uncapped → amount)."""
+        return cast(KeyBudgetTopupResponse, await self._call("POST", f"{_key_path(key_id)}/topup", {"amount": amount}))
+
+    async def promote(self, key_id: str) -> PromoteKeyResponse:
+        """``POST …/promote``: makes the key the superkey. JWT only server-side (a superkey gets 403)."""
+        return cast(PromoteKeyResponse, await self._call("POST", f"{_key_path(key_id)}/promote"))

relaygpu/_async/models.py

@@ -0,0 +1,75 @@
+"""The catalog, keyless (port of src/models.ts). ``models.get`` is the SDK's one resolver of route, ``model_in_body``,
+``async_default`` and schemas."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from .. import _clock
+from .. import _run_common as common
+from .._util import model_path
+from ..types import HealthResponse, ModelCatalog, ModelDetail, ModelRow, PricingResponse, TiersResponse
+
+if TYPE_CHECKING:
+    from .client import AsyncRelay
+
+
+class AsyncModels:
+    """``GET /v2/models`` and ``GET /v2/models/{name}`` (keyless)."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+        self._cache: dict[str, tuple[float, ModelDetail]] = {}
+
+    async def list(self, *, tag: str | None = None) -> list[ModelRow]:
+        """``GET /v2/models`` flattened: every model listed under ``auto``, once, optionally filtered by ``tag``
+        (e.g. ``text-to-video``)."""
+        res = await self._relay._http.request("GET", "/v2/models", no_auth=True)
+        data = cast(ModelCatalog, res.data)
+        seen: dict[str, ModelRow] = {}
+        for rows in (data.get("auto") or {}).values():
+            for row in rows or []:
+                seen.setdefault(row["name"], row)
+        rows_all = list(seen.values())
+        return [r for r in rows_all if r.get("tag") == tag] if tag else rows_all
+
+    async def get(self, name: str) -> ModelDetail:
+        """``GET /v2/models/{name}``: route, request/response schema, example, pricing, status. Cached per client for
+        5 minutes. An unknown name raises ``ModelNotFoundError`` (never cached); a retired model resolves with
+        ``status: "retired"``."""
+        now = _clock.monotonic()
+        hit = self._cache.get(name)
+        if hit is not None and hit[0] > now:
+            return hit[1]
+        res = await self._relay._http.request("GET", model_path(name), no_auth=True)
+        detail = cast(ModelDetail, res.data)
+        self._cache[name] = (now + common.MODEL_CACHE_SECONDS, detail)
+        return detail
+
+
+class AsyncPricing:
+    """``GET /v2/pricing``: list prices per mode and model, plus the ``media_storage`` per-file fees."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def get(self) -> PricingResponse:
+        res = await self._relay._http.request("GET", "/v2/pricing", no_auth=True)
+        return cast(PricingResponse, res.data)
+
+
+class AsyncTiers:
+    """``GET /v2/tiers``."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def list(self) -> TiersResponse:
+        res = await self._relay._http.request("GET", "/v2/tiers", no_auth=True)
+        return cast(TiersResponse, res.data)
+
+
+async def health(relay: AsyncRelay) -> HealthResponse:
+    """``GET /v2/health``: ``{status, version, commit}``."""
+    res = await relay._http.request("GET", "/v2/health", no_auth=True)
+    return cast(HealthResponse, res.data)