Skip to content

Document file operations #276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 2, 2024
Merged

Document file operations #276

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0deac30
Reword file input recommendations
mattt Jun 28, 2024
86e1a45
Document file methods
mattt Jun 28, 2024
f87c9c0
Document fileEncodingStrategy client constructor option
mattt Jun 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 109 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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.
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand Down
Loading