Introduce experimental FileOutput interface for models that output File and Path types

[aron]

This PR is a proposal to add a new FileOutput type to the client SDK to abstract away file outputs from Replicate models.

It can be enabled by passing the useFileOutput flag to the Replicate constructor.

const replicate = new Replicate({ useFileOutput: true });

When enabled any URLs or data-uris will be converted into a FileOutput type. This is essentially a ReadableStream that has two additional methods url() to return the underlying URL and blob() which will return a Blob() instance with the file data loaded into memory.

The intention here is to make it easier to work with file outputs and allows us to optimize the delivery of file assets to the client in future iterations.

Usage is as follows:

const [output] = await replicate.run("black-forest-labs/flux-schnell", { 
	  input: {
	    prompt: "astronaut riding a rocket like a horse"
	  }
});

For most basic cases you'll want to utilize either the url() or blob() methods depending on whether you want to directly consume the file or pass it on.

To access the file URL:

console.log(output.url()) // "https://delivery.replicate.com/..."

To consume the file directly:

// Assign an image directly to an image tag.
img.src = URL.createObjectURL(await output.blob());

Or for very large files they can be streamed:

for await (const chunk of output) {
  console.log(chunk); // UInt8Array
}

Or passed on to methods that support ReadableStream.

fs.writeFile("my-image.png", output);

An effort has been made to maintain backwards compatibility by implementing a toString() method which should cause the FileObject to act like a URL string.

const data = await fetch(output).then(r => r.blob()); // Blob

[mattt]

I like this. Really nice work, @aron. No comments and changes other than to add some doc comments. Quite happy with this approach.

[aron]

@mattt thoughts on transforming prediction.output from all API responses when this is enabled, rather than just the output of replicate.run()? I think that would be better for consistency.