# Replicate Provider

Replicate provides a marketplace to run any open-source model through a simple API. Perfect for experimentation and accessing diverse models including image generation, video, and specialized models.

## Setup

### Installation

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/replicate"
)
```

### Configuration

```go
provider := replicate.New(replicate.Config{
    APIKey: os.Getenv("REPLICATE_API_KEY"),
})

model, err := provider.LanguageModel("meta/meta-llama-3-70b-instruct")
```

### Get API Key

```bash
export REPLICATE_API_KEY=r8_...
```

## Available Models

### Language Models

| Model ID | Context | Price | Best For |
|----------|---------|-------|----------|
| meta/meta-llama-3-70b-instruct | 8K | $0.65/1M | General purpose |
| mistralai/mixtral-8x7b-instruct-v0.1 | 32K | $0.30/1M | Balanced |

### Image Generation

| Model ID | Quality | Price | Best For |
|----------|---------|-------|----------|
| stability-ai/sdxl | High | $0.0119/run | Images |
| black-forest-labs/flux-pro | Excellent | $0.055/run | Professional |
| black-forest-labs/flux-schnell | Good | $0.003/run | Fast |

### Video Generation

| Model ID | Quality | Price | Best For |
|----------|---------|-------|----------|
| stability-ai/stable-video-diffusion | Medium | $0.10/run | Video from image |

`provider.VideoModel(modelID)` accepts both forms Replicate uses:

- **Unversioned** — `"owner/model"` (no `:version`). Requests go to
  `POST /models/{owner}/{model}/predictions`, which always runs the
  model's latest version. This is now supported; previously only versioned
  IDs worked.
- **Versioned** — `"owner/model:version-hash"`. Requests go to
  `POST /predictions` with `version` in the body, pinning an exact version.

```go
videoModel, err := provider.VideoModel("stability-ai/stable-video-diffusion")
if err != nil {
    log.Fatal(err)
}

result, err := ai.GenerateVideo(ctx, ai.GenerateVideoOptions{
    Model:  videoModel,
    Prompt: ai.VideoPrompt{Text: "A boat sailing across a calm lake"},
})
```

`VideoModel` also implements `provider.VideoModelStarter` /
`VideoModelStatusChecker` for the async `ai.ExperimentalStartVideo` /
`ai.ExperimentalGetVideoStatus` calls.

## Examples

### Basic Text Generation

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/replicate"
)

func main() {
    ctx := context.Background()
    provider := replicate.New(replicate.Config{
        APIKey: os.Getenv("REPLICATE_API_KEY"),
    })

    model, err := provider.LanguageModel("meta/meta-llama-3-70b-instruct")
    if err != nil {
        log.Fatal(err)
    }

    result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{Model: model, Prompt: "Explain Replicate"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text)
}
```

### Image Generation

```go
imageModel, err := provider.ImageModel("black-forest-labs/flux-pro")
if err != nil {
    log.Fatal(err)
}

result, err := ai.GenerateImage(ctx, ai.GenerateImageOptions{
    Model:  imageModel,
    Prompt: "A cyberpunk city at night",
    Size:   "1024x1024",
})

fmt.Printf("Image bytes: %d\n", len(result.Images[0].Data))
```

## Best Practices

1. **Model Discovery**
   - Browse Replicate marketplace for models
   - Try different models easily
   - Great for prototyping

2. **Cost Management**
   - Pay-per-run pricing
   - Monitor usage carefully
   - Cache results when possible

3. **Use Cases**
   - Experimentation and testing
   - Specialized model access
   - Image/video generation

## Workflow Serialization

Replicate image models can cross a workflow boundary with
`providerutils.SerializeModel` / `DeserializeModel`. See
[Provider Serialization](https://goaisdk.com/docs/agents/workflow-agent.md#provider-serialization)
for the mechanism; video models are not yet serializable.

## See Also

- [Replicate Documentation](https://replicate.com/docs)
- [Model Marketplace](https://replicate.com/explore)