feat(api): add Files API methods

...and mark them as undocumented.

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 30
+configured_endpoints: 35
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/replicate%2Freplicate-client-efbc8cc2d74644b213e161d3e11e0589d1cef181fb318ea02c8eb6b00f245713.yml
 openapi_spec_hash: 13da0c06c900b61cd98ab678e024987a
-config_hash: 927b6ebc00ee115763ad69483bbf5566
+config_hash: e25b98bb6202d27e54fc6e08c7de80d8

README.md

@@ -28,17 +28,17 @@ import os
 from replicate import Replicate
 
 client = Replicate(
-    bearer_token=os.environ.get("REPLICATE_API_TOKEN"),  # This is the default and can be omitted
+    api_key=os.environ.get("REPLICATE_CLIENT_API_KEY"),  # This is the default and can be omitted
 )
 
 account = client.account.get()
 print(account.type)
 ```
 
-While you can provide a `bearer_token` keyword argument,
+While you can provide an `api_key` keyword argument,
 we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
-to add `REPLICATE_API_TOKEN="My Bearer Token"` to your `.env` file
-so that your Bearer Token is not stored in source control.
+to add `REPLICATE_CLIENT_API_KEY="My API Key"` to your `.env` file
+so that your API Key is not stored in source control.
 
 ## Async usage
 
@@ -50,7 +50,7 @@ import asyncio
 from replicate import AsyncReplicate
 
 client = AsyncReplicate(
-    bearer_token=os.environ.get("REPLICATE_API_TOKEN"),  # This is the default and can be omitted
+    api_key=os.environ.get("REPLICATE_CLIENT_API_KEY"),  # This is the default and can be omitted
 )
 
 
@@ -136,6 +136,24 @@ for prediction in first_page.results:
 # Remove `await` for non-async usage.
 ```
 
+## File uploads
+
+Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`.
+
+```python
+from pathlib import Path
+from replicate import Replicate
+
+client = Replicate()
+
+client.files.create(
+    content=Path("/path/to/file"),
+    filename="filename",
+)
+```
+
+The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically.
+
 ## Handling errors
 
 When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `replicate.APIConnectionError` is raised.

api.md

@@ -154,3 +154,11 @@ from replicate.types.webhooks.default import SecretGetResponse
 Methods:
 
 - <code title="get /webhooks/default/secret">client.webhooks.default.secret.<a href="./src/replicate/resources/webhooks/default/secret.py">get</a>() -> <a href="./src/replicate/types/webhooks/default/secret_get_response.py">SecretGetResponse</a></code>
+
+# Files
+
+Types:
+
+```python
+from replicate.types import FileCreateResponse, FileListResponse, FileGetResponse
+```

src/replicate/__init__.py

@@ -104,7 +104,7 @@
 
 from ._base_client import DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES
 
-bearer_token: str | None = None
+api_key: str | None = None
 
 base_url: str | _httpx.URL | None = None
 
@@ -125,14 +125,14 @@ class _ModuleClient(Replicate):
 
     @property  # type: ignore
     @override
-    def bearer_token(self) -> str | None:
-        return bearer_token
+    def api_key(self) -> str | None:
+        return api_key
 
-    @bearer_token.setter  # type: ignore
-    def bearer_token(self, value: str | None) -> None:  # type: ignore
-        global bearer_token
+    @api_key.setter  # type: ignore
+    def api_key(self, value: str | None) -> None:  # type: ignore
+        global api_key
 
-        bearer_token = value
+        api_key = value
 
     @property
     @override
@@ -210,7 +210,7 @@ def _load_client() -> Replicate:  # type: ignore[reportUnusedFunction]
 
     if _client is None:
         _client = _ModuleClient(
-            bearer_token=bearer_token,
+            api_key=api_key,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -230,6 +230,7 @@ def _reset_client() -> None:  # type: ignore[reportUnusedFunction]
 
 
 from ._module_client import (
+    files as files,
     models as models,
     account as account,
     hardware as hardware,

src/replicate/_client.py

@@ -31,7 +31,8 @@
 )
 
 if TYPE_CHECKING:
-    from .resources import models, account, hardware, webhooks, trainings, collections, deployments, predictions
+    from .resources import files, models, account, hardware, webhooks, trainings, collections, deployments, predictions
+    from .resources.files import FilesResource, AsyncFilesResource
     from .resources.account import AccountResource, AsyncAccountResource
     from .resources.hardware import HardwareResource, AsyncHardwareResource
     from .resources.trainings import TrainingsResource, AsyncTrainingsResource
@@ -55,12 +56,12 @@
 
 class Replicate(SyncAPIClient):
     # client options
-    bearer_token: str
+    api_key: str
 
     def __init__(
         self,
         *,
-        bearer_token: str | None = None,
+        api_key: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
@@ -82,15 +83,15 @@ def __init__(
     ) -> None:
         """Construct a new synchronous Replicate client instance.
 
-        This automatically infers the `bearer_token` argument from the `REPLICATE_API_TOKEN` environment variable if it is not provided.
+        This automatically infers the `api_key` argument from the `REPLICATE_CLIENT_API_KEY` environment variable if it is not provided.
         """
-        if bearer_token is None:
-            bearer_token = os.environ.get("REPLICATE_API_TOKEN")
-        if bearer_token is None:
+        if api_key is None:
+            api_key = os.environ.get("REPLICATE_CLIENT_API_KEY")
+        if api_key is None:
             raise ReplicateError(
-                "The bearer_token client option must be set either by passing bearer_token to the client or by setting the REPLICATE_API_TOKEN environment variable"
+                "The api_key client option must be set either by passing api_key to the client or by setting the REPLICATE_CLIENT_API_KEY environment variable"
             )
-        self.bearer_token = bearer_token
+        self.api_key = api_key
 
         if base_url is None:
             base_url = os.environ.get("REPLICATE_BASE_URL")
@@ -156,6 +157,12 @@ def webhooks(self) -> WebhooksResource:
 
         return WebhooksResource(self)
 
+    @cached_property
+    def files(self) -> FilesResource:
+        from .resources.files import FilesResource
+
+        return FilesResource(self)
+
     @cached_property
     def with_raw_response(self) -> ReplicateWithRawResponse:
         return ReplicateWithRawResponse(self)
@@ -172,8 +179,8 @@ def qs(self) -> Querystring:
     @property
     @override
     def auth_headers(self) -> dict[str, str]:
-        bearer_token = self.bearer_token
-        return {"Authorization": f"Bearer {bearer_token}"}
+        api_key = self.api_key
+        return {"Authorization": f"Bearer {api_key}"}
 
     @property
     @override
@@ -187,7 +194,7 @@ def default_headers(self) -> dict[str, str | Omit]:
     def copy(
         self,
         *,
-        bearer_token: str | None = None,
+        api_key: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.Client | None = None,
@@ -221,7 +228,7 @@ def copy(
 
         http_client = http_client or self._client
         return self.__class__(
-            bearer_token=bearer_token or self.bearer_token,
+            api_key=api_key or self.api_key,
             base_url=base_url or self.base_url,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
@@ -271,12 +278,12 @@ def _make_status_error(
 
 class AsyncReplicate(AsyncAPIClient):
     # client options
-    bearer_token: str
+    api_key: str
 
     def __init__(
         self,
         *,
-        bearer_token: str | None = None,
+        api_key: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
@@ -298,15 +305,15 @@ def __init__(
     ) -> None:
         """Construct a new async AsyncReplicate client instance.
 
-        This automatically infers the `bearer_token` argument from the `REPLICATE_API_TOKEN` environment variable if it is not provided.
+        This automatically infers the `api_key` argument from the `REPLICATE_CLIENT_API_KEY` environment variable if it is not provided.
         """
-        if bearer_token is None:
-            bearer_token = os.environ.get("REPLICATE_API_TOKEN")
-        if bearer_token is None:
+        if api_key is None:
+            api_key = os.environ.get("REPLICATE_CLIENT_API_KEY")
+        if api_key is None:
             raise ReplicateError(
-                "The bearer_token client option must be set either by passing bearer_token to the client or by setting the REPLICATE_API_TOKEN environment variable"
+                "The api_key client option must be set either by passing api_key to the client or by setting the REPLICATE_CLIENT_API_KEY environment variable"
             )
-        self.bearer_token = bearer_token
+        self.api_key = api_key
 
         if base_url is None:
             base_url = os.environ.get("REPLICATE_BASE_URL")
@@ -372,6 +379,12 @@ def webhooks(self) -> AsyncWebhooksResource:
 
         return AsyncWebhooksResource(self)
 
+    @cached_property
+    def files(self) -> AsyncFilesResource:
+        from .resources.files import AsyncFilesResource
+
+        return AsyncFilesResource(self)
+
     @cached_property
     def with_raw_response(self) -> AsyncReplicateWithRawResponse:
         return AsyncReplicateWithRawResponse(self)
@@ -388,8 +401,8 @@ def qs(self) -> Querystring:
     @property
     @override
     def auth_headers(self) -> dict[str, str]:
-        bearer_token = self.bearer_token
-        return {"Authorization": f"Bearer {bearer_token}"}
+        api_key = self.api_key
+        return {"Authorization": f"Bearer {api_key}"}
 
     @property
     @override
@@ -403,7 +416,7 @@ def default_headers(self) -> dict[str, str | Omit]:
     def copy(
         self,
         *,
-        bearer_token: str | None = None,
+        api_key: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.AsyncClient | None = None,
@@ -437,7 +450,7 @@ def copy(
 
         http_client = http_client or self._client
         return self.__class__(
-            bearer_token=bearer_token or self.bearer_token,
+            api_key=api_key or self.api_key,
             base_url=base_url or self.base_url,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
@@ -539,6 +552,12 @@ def webhooks(self) -> webhooks.WebhooksResourceWithRawResponse:
 
         return WebhooksResourceWithRawResponse(self._client.webhooks)
 
+    @cached_property
+    def files(self) -> files.FilesResourceWithRawResponse:
+        from .resources.files import FilesResourceWithRawResponse
+
+        return FilesResourceWithRawResponse(self._client.files)
+
 
 class AsyncReplicateWithRawResponse:
     _client: AsyncReplicate
@@ -594,6 +613,12 @@ def webhooks(self) -> webhooks.AsyncWebhooksResourceWithRawResponse:
 
         return AsyncWebhooksResourceWithRawResponse(self._client.webhooks)
 
+    @cached_property
+    def files(self) -> files.AsyncFilesResourceWithRawResponse:
+        from .resources.files import AsyncFilesResourceWithRawResponse
+
+        return AsyncFilesResourceWithRawResponse(self._client.files)
+
 
 class ReplicateWithStreamedResponse:
     _client: Replicate
@@ -649,6 +674,12 @@ def webhooks(self) -> webhooks.WebhooksResourceWithStreamingResponse:
 
         return WebhooksResourceWithStreamingResponse(self._client.webhooks)
 
+    @cached_property
+    def files(self) -> files.FilesResourceWithStreamingResponse:
+        from .resources.files import FilesResourceWithStreamingResponse
+
+        return FilesResourceWithStreamingResponse(self._client.files)
+
 
 class AsyncReplicateWithStreamedResponse:
     _client: AsyncReplicate
@@ -704,6 +735,12 @@ def webhooks(self) -> webhooks.AsyncWebhooksResourceWithStreamingResponse:
 
         return AsyncWebhooksResourceWithStreamingResponse(self._client.webhooks)
 
+    @cached_property
+    def files(self) -> files.AsyncFilesResourceWithStreamingResponse:
+        from .resources.files import AsyncFilesResourceWithStreamingResponse
+
+        return AsyncFilesResourceWithStreamingResponse(self._client.files)
+
 
 Client = Replicate
 

src/replicate/_files.py

@@ -34,7 +34,7 @@ def assert_is_file_content(obj: object, *, key: str | None = None) -> None:
     if not is_file_content(obj):
         prefix = f"Expected entry at `{key}`" if key is not None else f"Expected file input `{obj!r}`"
         raise RuntimeError(
-            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead."
+            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead. See https://github.com/replicate/replicate-python-stainless/tree/main#file-uploads"
         ) from None
 
 

src/replicate/_module_client.py

@@ -6,6 +6,7 @@
 from typing_extensions import override
 
 if TYPE_CHECKING:
+    from .resources.files import FilesResource
     from .resources.account import AccountResource
     from .resources.hardware import HardwareResource
     from .resources.trainings import TrainingsResource
@@ -19,6 +20,12 @@
 from ._utils import LazyProxy
 
 
+class FilesResourceProxy(LazyProxy["FilesResource"]):
+    @override
+    def __load__(self) -> FilesResource:
+        return _load_client().files
+
+
 class ModelsResourceProxy(LazyProxy["ModelsResource"]):
     @override
     def __load__(self) -> ModelsResource:
@@ -67,6 +74,7 @@ def __load__(self) -> PredictionsResource:
         return _load_client().predictions
 
 
+files: FilesResource = FilesResourceProxy().__as_proxied__()
 models: ModelsResource = ModelsResourceProxy().__as_proxied__()
 account: AccountResource = AccountResourceProxy().__as_proxied__()
 hardware: HardwareResource = HardwareResourceProxy().__as_proxied__()