Skip to content

Commit 9b5df12

Browse files
authored
Document file operations (#276)
* Reword file input recommendations * Document file methods * Document fileEncodingStrategy client constructor option
1 parent fa38a54 commit 9b5df12

File tree

1 file changed

+109
-8
lines changed

1 file changed

+109
-8
lines changed

README.md

+109-8
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,9 @@ console.log(prediction.output);
7777
// ['https://replicate.delivery/pbxt/RoaxeXqhL0xaYyLm6w3bpGwF5RaNBjADukfFnMbhOyeoWBdhA/out-0.png']
7878
```
7979

80-
To run a model that takes a file input you can pass the data directly or pass a URL to a publicly accessible file.
80+
To run a model that takes a file input you can pass either
81+
a URL to a publicly accessible file on the Internet
82+
or a handle to a file on your local device.
8183

8284
```js
8385
const fs = require("node:fs/promises");
@@ -93,6 +95,10 @@ const output = await replicate.run(model, { input });
9395
// ['https://replicate.delivery/mgxm/e7b0e122-9daa-410e-8cde-006c7308ff4d/output.png']
9496
```
9597

98+
> [!NOTE]
99+
> File handle inputs are automatically uploaded to Replicate.
100+
> See [`replicate.files.create`](#replicatefilescreate) for more information.
101+
96102
### Webhooks
97103

98104
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) {
179185
console.log(body);
180186
return NextResponse.json({ detail: "Webhook received (but not validated)" }, { status: 200 });
181187
}
182-
188+
183189
const webhookIsValid = await validateWebhook(request.clone(), secret);
184190

185191
if (!webhookIsValid) {
@@ -209,12 +215,14 @@ Currently in order to support the module format used by `replicate` you'll need
209215
const replicate = new Replicate(options);
210216
```
211217

212-
| name | type | description |
213-
| ------------------- | -------- | --------------------------------------------------------------------------------- |
214-
| `options.auth` | string | **Required**. API access token |
215-
| `options.userAgent` | string | Identifier of your app. Defaults to `replicate-javascript/${packageJSON.version}` |
216-
| `options.baseUrl` | string | Defaults to https://api.replicate.com/v1 |
217-
| `options.fetch` | function | Fetch function to use. Defaults to `globalThis.fetch` |
218+
| name | type | description |
219+
| ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
220+
| `options.auth` | string | **Required**. API access token |
221+
| `options.userAgent` | string | Identifier of your app. Defaults to `replicate-javascript/${packageJSON.version}` |
222+
| `options.baseUrl` | string | Defaults to https://api.replicate.com/v1 |
223+
| `options.fetch` | function | Fetch function to use. Defaults to `globalThis.fetch` |
224+
| `options.fileEncodingStrategy` | string | Determines the file encoding strategy to use. Possible values: `"default"`, `"upload"`, or `"data-uri"`. Defaults to `"default"` |
225+
218226

219227
The client makes requests to Replicate's API using
220228
[fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
@@ -983,6 +991,99 @@ const response = await replicate.deployments.update(deploymentOwner, deploymentN
983991
}
984992
```
985993

994+
### `replicate.files.create`
995+
996+
Upload a file to Replicate.
997+
998+
> [!TIP]
999+
> The client library calls this endpoint automatically to upload the contents of
1000+
> file handles provided as prediction and training inputs.
1001+
> You don't need to call this method directly unless you want more control.
1002+
> For example, you might want to reuse a file across multiple predictions
1003+
> without re-uploading it each time,
1004+
> or you may want to set custom metadata on the file resource.
1005+
>
1006+
> You can configure how a client handles file handle inputs
1007+
> by setting the `fileEncodingStrategy` option in the
1008+
> [client constructor](#constructor).
1009+
1010+
```js
1011+
const response = await replicate.files.create(file, metadata);
1012+
```
1013+
1014+
| name | type | description |
1015+
| ---------- | --------------------- | ---------------------------------------------------------- |
1016+
| `file` | Blob, File, or Buffer | **Required**. The file to upload. |
1017+
| `metadata` | object | Optional. User-provided metadata associated with the file. |
1018+
1019+
```jsonc
1020+
{
1021+
"id": "MTQzODcyMDct0YjZkLWE1ZGYtMmRjZTViNWIwOGEyNjNhNS0",
1022+
"name": "photo.webp",
1023+
"content_type": "image/webp",
1024+
"size": 96936,
1025+
"etag": "f211779ff7502705bbf42e9874a17ab3",
1026+
"checksums": {
1027+
"sha256": "7282eb6991fa4f38d80c312dc207d938c156d714c94681623aedac846488e7d3",
1028+
"md5": "f211779ff7502705bbf42e9874a17ab3"
1029+
},
1030+
"metadata": {
1031+
"customer_reference_id": "123"
1032+
},
1033+
"created_at": "2024-06-28T10:16:04.062Z",
1034+
"expires_at": "2024-06-29T10:16:04.062Z",
1035+
"urls": {
1036+
"get": "https://api.replicate.com/v1/files/MTQzODcyMDct0YjZkLWE1ZGYtMmRjZTViNWIwOGEyNjNhNS0"
1037+
}
1038+
}
1039+
```
1040+
1041+
Files uploaded to Replicate using this endpoint expire after 24 hours.
1042+
1043+
Pass the `urls.get` property of a file resource
1044+
to use it as an input when running a model on Replicate.
1045+
The value of `urls.get` is opaque,
1046+
and shouldn't be inferred from other attributes.
1047+
1048+
The contents of a file are only made accessible to a model running on Replicate,
1049+
and only when passed as a prediction or training input
1050+
by the user or organization who created the file.
1051+
1052+
### `replicate.files.list`
1053+
1054+
List all files you've uploaded.
1055+
1056+
```js
1057+
const response = await replicate.files.list();
1058+
```
1059+
1060+
### `replicate.files.get`
1061+
1062+
Get metadata for a specific file.
1063+
1064+
```js
1065+
const response = await replicate.files.get(file_id);
1066+
```
1067+
1068+
| name | type | description |
1069+
| --------- | ------ | --------------------------------- |
1070+
| `file_id` | string | **Required**. The ID of the file. |
1071+
1072+
### `replicate.files.delete`
1073+
1074+
Delete a file.
1075+
1076+
Files uploaded using the `replicate.files.create` method expire after 24 hours.
1077+
You can use this method to delete them sooner.
1078+
1079+
```js
1080+
const response = await replicate.files.delete(file_id);
1081+
```
1082+
1083+
| name | type | description |
1084+
| --------- | ------ | --------------------------------- |
1085+
| `file_id` | string | **Required**. The ID of the file. |
1086+
9861087
### `replicate.paginate`
9871088

9881089
Pass another method as an argument to iterate over results

0 commit comments

Comments
 (0)