Document file operations (#276)

mattt · web-flow · commit 9b5df12c0ad7 · 2024-07-02T09:32:31.000-07:00
* Reword file input recommendations

* Document file methods

* Document fileEncodingStrategy client constructor option
diff --git a/README.md b/README.md
@@ -77,7 +77,9 @@ console.log(prediction.output);
 // ['https://replicate.delivery/pbxt/RoaxeXqhL0xaYyLm6w3bpGwF5RaNBjADukfFnMbhOyeoWBdhA/out-0.png']
 ```
 
-To run a model that takes a file input you can pass the data directly or pass a URL to a publicly accessible file.
+To run a model that takes a file input you can pass either
+a URL to a publicly accessible file on the Internet
+or a handle to a file on your local device.
 
 ```js
 const fs = require("node:fs/promises");
@@ -93,6 +95,10 @@ const output = await replicate.run(model, { input });
 // ['https://replicate.delivery/mgxm/e7b0e122-9daa-410e-8cde-006c7308ff4d/output.png']
 ```
 
+> [!NOTE]
+> File handle inputs are automatically uploaded to Replicate.
+> See [`replicate.files.create`](#replicatefilescreate) for more information.
+
 ### Webhooks
 
 Webhooks provide real-time updates about your prediction. Specify an endpoint when you create a prediction, and Replicate will send HTTP POST requests to that URL when the prediction is created, updated, and finished.
@@ -179,7 +185,7 @@ export async function POST(request) {
     console.log(body);
     return NextResponse.json({ detail: "Webhook received (but not validated)" }, { status: 200 });
   }
-  
+
   const webhookIsValid = await validateWebhook(request.clone(), secret);
 
   if (!webhookIsValid) {
@@ -209,12 +215,14 @@ Currently in order to support the module format used by `replicate` you'll need
 const replicate = new Replicate(options);
 ```
 
-| name                | type     | description                                                                       |
-| ------------------- | -------- | --------------------------------------------------------------------------------- |
-| `options.auth`      | string   | **Required**. API access token                                                    |
-| `options.userAgent` | string   | Identifier of your app. Defaults to `replicate-javascript/${packageJSON.version}` |
-| `options.baseUrl`   | string   | Defaults to https://api.replicate.com/v1                                          |
-| `options.fetch`     | function | Fetch function to use. Defaults to `globalThis.fetch`                             |
+| name                           | type     | description                                                                                                                      |
+| ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `options.auth`                 | string   | **Required**. API access token                                                                                                   |
+| `options.userAgent`            | string   | Identifier of your app. Defaults to `replicate-javascript/${packageJSON.version}`                                                |
+| `options.baseUrl`              | string   | Defaults to https://api.replicate.com/v1                                                                                         |
+| `options.fetch`                | function | Fetch function to use. Defaults to `globalThis.fetch`                                                                            |
+| `options.fileEncodingStrategy` | string   | Determines the file encoding strategy to use. Possible values: `"default"`, `"upload"`, or `"data-uri"`. Defaults to `"default"` |
+
 
 The client makes requests to Replicate's API using
 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
@@ -983,6 +991,99 @@ const response = await replicate.deployments.update(deploymentOwner, deploymentN
 }
 ```
 
+### `replicate.files.create`
+
+Upload a file to Replicate.
+
+> [!TIP]
+> The client library calls this endpoint automatically to upload the contents of
+> file handles provided as prediction and training inputs.
+> You don't need to call this method directly unless you want more control.
+> For example, you might want to reuse a file across multiple predictions
+> without re-uploading it each time,
+> or you may want to set custom metadata on the file resource.
+>
+> You can configure how a client handles file handle inputs
+> by setting the `fileEncodingStrategy` option in the
+> [client constructor](#constructor).
+
+```js
+const response = await replicate.files.create(file, metadata);
+```
+
+| name       | type                  | description                                                |
+| ---------- | --------------------- | ---------------------------------------------------------- |
+| `file`     | Blob, File, or Buffer | **Required**. The file to upload.                          |
+| `metadata` | object                | Optional. User-provided metadata associated with the file. |
+
+```jsonc
+{
+    "id": "MTQzODcyMDct0YjZkLWE1ZGYtMmRjZTViNWIwOGEyNjNhNS0",
+    "name": "photo.webp",
+    "content_type": "image/webp",
+    "size": 96936,
+    "etag": "f211779ff7502705bbf42e9874a17ab3",
+    "checksums": {
+        "sha256": "7282eb6991fa4f38d80c312dc207d938c156d714c94681623aedac846488e7d3",
+        "md5": "f211779ff7502705bbf42e9874a17ab3"
+    },
+    "metadata": {
+        "customer_reference_id": "123"
+    },
+    "created_at": "2024-06-28T10:16:04.062Z",
+    "expires_at": "2024-06-29T10:16:04.062Z",
+    "urls": {
+        "get": "https://api.replicate.com/v1/files/MTQzODcyMDct0YjZkLWE1ZGYtMmRjZTViNWIwOGEyNjNhNS0"
+    }
+}
+```
+
+Files uploaded to Replicate using this endpoint expire after 24 hours.
+
+Pass the `urls.get` property of a file resource
+to use it as an input when running a model on Replicate.
+The value of `urls.get` is opaque,
+and shouldn't be inferred from other attributes.
+
+The contents of a file are only made accessible to a model running on Replicate,
+and only when passed as a prediction or training input
+by the user or organization who created the file.
+
+### `replicate.files.list`
+
+List all files you've uploaded.
+
+```js
+const response = await replicate.files.list();
+```
+
+### `replicate.files.get`
+
+Get metadata for a specific file.
+
+```js
+const response = await replicate.files.get(file_id);
+```
+
+| name      | type   | description                       |
+| --------- | ------ | --------------------------------- |
+| `file_id` | string | **Required**. The ID of the file. |
+
+### `replicate.files.delete`
+
+Delete a file.
+
+Files uploaded using the `replicate.files.create` method expire after 24 hours.
+You can use this method to delete them sooner.
+
+```js
+const response = await replicate.files.delete(file_id);
+```
+
+| name      | type   | description                       |
+| --------- | ------ | --------------------------------- |
+| `file_id` | string | **Required**. The ID of the file. |
+
 ### `replicate.paginate`
 
 Pass another method as an argument to iterate over results
