replicate

Documentation

Overview

Package replicate implements Replicate's official prediction-job protocol and schema-bound image and speech adapters.

Replicate is not a modality API with one shared image or TTS request shape. Every model version publishes an independent OpenAPI input/output schema. Accordingly, ImageModel and AudioTTSModel require an explicit schema binding at construction and reject model overrides. Provider-specific fields remain in PredictionRequest.Input under ImageRequestExtensionKey or SpeechRequestExtensionKey; Core fields are mapped only through the declared binding. This prevents a field named "seed", "voice", or "width" on one model from being guessed for an unrelated model.

Model identifiers use two official forms:

• owner/name for official models, sent to /v1/models/{owner}/{name}/predictions;
• owner/name:version for community models, sent to /v1/predictions with the immutable version in the request body.

Predictions run asynchronously. The high-level adapters submit, poll to a terminal state, validate the configured output schema, and copy ephemeral output files before Replicate removes API prediction data.

See https://replicate.com/docs/reference/http and each model's API schema.

Index

• Constants
• type AudioTTSModel
  • func NewAudioTTSModel(config AudioTTSModelConfig) (*AudioTTSModel, error)
  • func (a *AudioTTSModel) Call(ctx context.Context, req *tts.Request) (*tts.Response, error)
• type AudioTTSModelConfig
  • func (a AudioTTSModelConfig) Validate() error
• type FileOutputKind
• type ImageInputSchema
  • func FluxSchnellImageInputSchema() ImageInputSchema
  • func (i ImageInputSchema) Clone() ImageInputSchema
  • func (i ImageInputSchema) Validate() error
• type ImageModel
  • func NewImageModel(config ImageModelConfig) (*ImageModel, error)
  • func (i *ImageModel) Call(ctx context.Context, req *image.Request) (*image.Response, error)
• type ImageModelConfig
  • func (i ImageModelConfig) Validate() error
• type SpeechInputSchema
  • func XTTSV2SpeechInputSchema() SpeechInputSchema
  • func (s SpeechInputSchema) Validate() error

Constants

const (
	ImageRequestExtensionKey   = "replicate/image_request"
	SpeechRequestExtensionKey  = "replicate/speech_request"
	ImageResponseExtensionKey  = "replicate/image_response"
	SpeechResponseExtensionKey = "replicate/speech_response"

	// DefaultBaseURL is Replicate's production API root.
	DefaultBaseURL = "https://api.replicate.com/v1"

	// DefaultPollIntervalSeconds is how long Call waits between
	// status polls. Image jobs on Replicate take anywhere from 1s
	// (flux-schnell) to 30s (flux-1.1-pro-ultra, SDXL with high
	// step count); 1s is short enough to hide tail latency without
	// hammering the API.
	DefaultPollIntervalSeconds = 1

	// DefaultPollTimeoutSeconds is the wall-clock cap on a single
	// image generation. Bumps above 120s should target slow models
	// like SDXL with high inference steps or large-batch num_outputs.
	DefaultPollTimeoutSeconds = 180

	// DefaultTTSPollTimeoutSeconds is the wall-clock cap on a TTS
	// job. Bark and especially Tortoise-TTS can spend a long time
	// on cold starts plus generation, so the cap is set higher than image.
	DefaultTTSPollTimeoutSeconds = 300
)

const (
	// ModelFluxSchnell is the cheapest / fastest FLUX (4-step
	// distilled, ~1s).
	ModelFluxSchnell = "black-forest-labs/flux-schnell"

	// ModelFluxDev is the open-weights FLUX dev model.
	ModelFluxDev = "black-forest-labs/flux-dev"

	// ModelFluxPro is the original commercial FLUX (50 steps).
	ModelFluxPro = "black-forest-labs/flux-pro"

	// ModelFlux11Pro (flux-1.1-pro) is the newer pro variant with
	// improved prompt adherence.
	ModelFlux11Pro = "black-forest-labs/flux-1.1-pro"

	// ModelFlux11ProUltra (flux-1.1-pro-ultra) targets up-to-4MP
	// renders.
	ModelFlux11ProUltra = "black-forest-labs/flux-1.1-pro-ultra"

	// ModelFluxKontextPro / Max are FLUX's instruction-driven editing
	// models — pass an input image via Extra "input_image" + a prompt
	// describing the edit.
	ModelFluxKontextPro = "black-forest-labs/flux-kontext-pro"
	ModelFluxKontextMax = "black-forest-labs/flux-kontext-max"

	// ModelIdeogramV2 is Ideogram V2 — strong on typography and
	// poster compositions.
	ModelIdeogramV2 = "ideogram-ai/ideogram-v2"

	// ModelIdeogramV2Turbo is the fast / cheap Ideogram variant.
	ModelIdeogramV2Turbo = "ideogram-ai/ideogram-v2-turbo"
)

Official image model ids on Replicate. The unversioned owner/name form is valid only for official models and routes through the official-model prediction endpoint. Bind each id to its current OpenAPI schema before using it with ImageModel.

const (
	ModelXTTSV2 = "lucataco/xtts-v2:684bc3855b37866c0c65add2ff39c78f3dea3f4ff103a436465326e0f438d55e"
)

ModelXTTSV2 is a version-pinned community model id. Community-model predictions require an immutable version; using owner/name without a version would incorrectly target Replicate's official-model endpoint.

const (
	Provider = "Replicate"
)

Types

type AudioTTSModel

type AudioTTSModel struct {
	// contains filtered or unexported fields
}

AudioTTSModel wraps one explicitly bound Replicate TTS model version. It never infers fields from a model name: community models have independent, versioned schemas and must be constructed with the matching binding.

func NewAudioTTSModel

func NewAudioTTSModel(config AudioTTSModelConfig) (*AudioTTSModel, error)

func (*AudioTTSModel) Call

func (a *AudioTTSModel) Call(ctx context.Context, req *tts.Request) (*tts.Response, error)

type AudioTTSModelConfig

type AudioTTSModelConfig struct {
	APIKey         string
	DefaultOptions tts.Options
	InputSchema    SpeechInputSchema
	BaseURL        string
	HTTPClient     *http.Client

	// PollInterval / PollTimeout configure the synchronous wrapper
	// around Replicate's async generation. Zero values fall back to
	// the package defaults; community TTS jobs can include cold-start
	// latency, so PollTimeout defaults higher than image.
	PollInterval time.Duration
	PollTimeout  time.Duration
}

func (AudioTTSModelConfig) Validate

func (a AudioTTSModelConfig) Validate() error

type FileOutputKind

type FileOutputKind string

FileOutputKind identifies the exact file-output schema declared by a Replicate model version.

const (
	FileOutputURI     FileOutputKind = "uri"
	FileOutputURIList FileOutputKind = "uri_list"
)

type ImageInputSchema

type ImageInputSchema struct {
	PromptKey         string
	NegativePromptKey string
	WidthKey          string
	HeightKey         string
	SeedKey           string
	OutputFormatKey   string
	OutputFormats     map[string]string
	OutputKind        FileOutputKind
}

ImageInputSchema explicitly binds provider-neutral image fields to one Replicate model's OpenAPI input/output schema. Empty optional keys mean the model cannot represent that Core option; setting the option then fails instead of guessing a similarly named provider field.

func FluxSchnellImageInputSchema

func FluxSchnellImageInputSchema() ImageInputSchema

FluxSchnellImageInputSchema returns the current official schema binding for black-forest-labs/flux-schnell. Dimensions, seed, and negative prompt are intentionally absent because that model's current schema does not expose them.

func (ImageInputSchema) Clone

func (i ImageInputSchema) Clone() ImageInputSchema

func (ImageInputSchema) Validate

func (i ImageInputSchema) Validate() error

type ImageModel

type ImageModel struct {
	// contains filtered or unexported fields
}

ImageModel wraps one explicitly bound Replicate image-model schema. A model override is rejected because Replicate models do not share an input or output contract; construct another adapter with the matching schema instead.

func NewImageModel

func NewImageModel(config ImageModelConfig) (*ImageModel, error)

func (*ImageModel) Call

func (i *ImageModel) Call(ctx context.Context, req *image.Request) (*image.Response, error)

type ImageModelConfig

type ImageModelConfig struct {
	APIKey         string
	DefaultOptions image.Options
	InputSchema    ImageInputSchema
	BaseURL        string
	HTTPClient     *http.Client

	// PollInterval / PollTimeout configure the synchronous wrapper
	// around Replicate's async generation. Zero values fall back to
	// the package defaults.
	PollInterval time.Duration
	PollTimeout  time.Duration
}

func (ImageModelConfig) Validate

func (i ImageModelConfig) Validate() error

type SpeechInputSchema

type SpeechInputSchema struct {
	TextKey       string
	VoiceKey      string
	SpeedKey      string
	VoiceRequired bool
	OutputKind    FileOutputKind
}

SpeechInputSchema explicitly binds Core speech fields to one Replicate model version's OpenAPI schema.

func XTTSV2SpeechInputSchema

func XTTSV2SpeechInputSchema() SpeechInputSchema

XTTSV2SpeechInputSchema returns the official schema binding for the pinned ModelXTTSV2 version.

func (SpeechInputSchema) Validate

func (s SpeechInputSchema) Validate() error