A model’s predict function can produce file output by yielding or returning a cog.Path or cog.File value.
Default Behavior (Base64 Data URLs)
By default, files are returned as a base64-encoded data URL.
Request
curl http://localhost:5001/predictions -X POST \
--header "Content-Type: application/json" \
--data '{
"input": {"prompt": "A picture of an onion with sunglasses"}
}'
Response
{
"status": "succeeded",
"output": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}
Custom Upload URLs
When creating a prediction synchronously, the client can configure a base URL to upload output files to instead by setting the output_file_prefix parameter in the request body.
Request
curl http://localhost:5001/predictions -X POST \
--header "Content-Type: application/json" \
--data '{
"input": {"prompt": "A picture of an onion with sunglasses"},
"output_file_prefix": "https://example.com/upload"
}'
Base URL where output files will be uploaded. When the model produces a file output, the server will upload the file to this URL and return the resulting URL in the response.
Upload Request
When the model produces a file output, the server sends the following request to upload the file to the configured URL:
PUT /upload HTTP/1.1
Host: example.com
Content-Type: multipart/form-data
--boundary
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png
<binary data>
--boundary--
Successful Upload Response
If the upload succeeds, the server responds with output:
{
"status": "succeeded",
"output": "http://example.com/upload/image.png"
}
Failed Upload
If the upload fails, the server responds with an error.
Asynchronous Predictions with File Uploads
File uploads for predictions created asynchronously require --upload-url to be specified when starting the HTTP server.
docker run -d -p 5001:5000 my-model \
python -m cog.server.http --upload-url=https://example.com/upload
Server Configuration
—upload-url
Specifies the base URL where files from asynchronous predictions will be uploaded.
docker run -d -p 5001:5000 my-model \
python -m cog.server.http --upload-url=https://example.com/upload
Example: Model with File Output
Here’s an example of a Cog model that produces file output:
from cog import BasePredictor, Path
import PIL.Image
class Predictor(BasePredictor):
def predict(self, prompt: str) -> Path:
# Generate an image
image = generate_image(prompt)
# Save to a temporary file
output_path = Path("/tmp/output.png")
image.save(output_path)
return output_path
Upload Endpoint Requirements
Your upload endpoint must:
- Accept PUT requests with
multipart/form-data content
- Handle a form field named
file containing the binary data
- Return a successful status code (2xx) if the upload succeeds
- Optionally return the URL where the file can be accessed
Example Upload Endpoint (Python/Flask)
from flask import Flask, request
import os
app = Flask(__name__)
@app.route('/upload', methods=['PUT'])
def upload_file():
if 'file' not in request.files:
return {'error': 'No file part'}, 400
file = request.files['file']
if file.filename == '':
return {'error': 'No selected file'}, 400
# Save the file
file_path = os.path.join('/uploads', file.filename)
file.save(file_path)
# Return the URL where the file can be accessed
return {'url': f'https://example.com/uploads/{file.filename}'}, 200
File Types
Cog automatically detects the MIME type of uploaded files based on the file extension. Common types include:
.png → image/png.jpg, .jpeg → image/jpeg.gif → image/gif.mp4 → video/mp4.wav → audio/wav.json → application/json.txt → text/plain