Metadata-Version: 2.4
Name: replicate-predictions-downloader
Version: 1.1.0
Summary: Download and organize all your Replicate predictions, including images, videos, and metadata
Project-URL: Homepage, https://github.com/closestfriend/replicate-predictions-downloader-py
Project-URL: Repository, https://github.com/closestfriend/replicate-predictions-downloader-py
Project-URL: Issues, https://github.com/closestfriend/replicate-predictions-downloader-py/issues
Author-email: Hunter Shokrian <hnshokrian@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ai-art,archive,backup,batch-download,cli,downloader,machine-learning,predictions,replicate,stable-diffusion
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: replicate>=0.20.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# Replicate Predictions Downloader (Python)

Download and organize all your [Replicate](https://replicate.com) predictions, including images, videos, 3D models, and metadata.

## Why

Replicate doesn't keep your prediction data forever. Per their [data retention policy](https://replicate.com/docs/topics/predictions/data-retention), predictions created **via the API** have their inputs, outputs, files, and logs automatically removed **after one hour** by default. Predictions made on the website are kept indefinitely, but output files still need downloading if you want local copies. This tool grabs everything while it's still there.

## Features

- **Batch download** all your Replicate prediction outputs
- **Organize by model** into clean directory structures
- **Smart filenames** with dates, model names, and prompt snippets
- **ZIP archives** for each model for easy backup
- **Date filtering** - download predictions from specific time ranges
- **Incremental downloads** - only fetch new predictions since last run
- **Full metadata export** as JSON

## Installation

```bash
pip install replicate-predictions-downloader
```

Or with pipx for isolated CLI usage:

```bash
pipx install replicate-predictions-downloader
```

## Setup

1. Get your API token from [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens)

2. Set your token:
   ```bash
   export REPLICATE_API_TOKEN=your_token_here
   ```

   Or create a `.env` file:
   ```
   REPLICATE_API_TOKEN=your_token_here
   ```

## Usage

### Download all predictions

```bash
replicate-downloader
```

### Download predictions from a specific date

```bash
replicate-downloader --since "2024-01-15"
replicate-downloader --since "7 days ago"
replicate-downloader --since yesterday
```

### Download predictions in a date range

```bash
replicate-downloader --since "2024-01-01" --until "2024-06-30"
```

### Incremental download (since last run)

```bash
replicate-downloader --last-run
```

## Output Structure

```
replicate_outputs_2024-01-15/
├── by-model/
│   ├── stable-diffusion/
│   │   ├── 2024-01-15_stable-diffusion_a-photo-of-an-astronaut_abc123.png
│   │   ├── 2024-01-15_stable-diffusion_sunset-over-mountains_def456.png
│   │   └── abc123_metadata.json
│   ├── stable-diffusion.zip
│   ├── flux-pro/
│   │   └── ...
│   └── flux-pro.zip
└── replicate_metadata_2024-01-15.json
```

## Python API

You can also use the downloader programmatically:

```python
from replicate_downloader import ReplicateDownloader

downloader = ReplicateDownloader(
    api_token="your_token",  # or use REPLICATE_API_TOKEN env var
    since="7 days ago",
)
downloader.run()
```

## Options

| Option | Description |
|--------|-------------|
| `-s, --since DATE` | Download predictions created since this date |
| `-u, --until DATE` | Download predictions created until this date |
| `-l, --last-run` | Only download predictions since the last successful run |
| `--all` | Download all predictions (default) |
| `--version` | Show version |
| `--help` | Show help |

## Date Formats

The `--since` and `--until` options support:

- ISO format: `2024-01-15`
- Relative: `yesterday`, `7 days ago`, `2 weeks ago`, `1 month ago`

## Related

- [replicate-predictions-downloader](https://www.npmjs.com/package/replicate-predictions-downloader) - Node.js version
- [Replicate Python SDK](https://github.com/replicate/replicate-python)

## License

MIT
