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 SpeechModel require an explicit schema binding at construction and reject model overrides. Provider-specific fields remain in the input object 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 references use owner/name, owner/name:64-character-version, or a bare 64-character version. Every form uses POST /v1/predictions with version in the body, so a model reference cannot change the request URL.
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. Downloads allow the configured endpoint origin and HTTPS replicate.delivery hosts on the standard port. The final transport checks the URL and explicit Host authority after the supplied redirect policy. Delivery requests carry no credentials. A supplied HTTP client is copied; the host retains ownership of its transport and cookie jar, and a typed-nil transport uses the default.
Polling waits only on the two statuses the prediction lifecycle documents as still running, "starting" and "processing". Every other status ends the call, including "aborted", which means the prediction exceeded its deadline before it could start and so will never advance. Waiting one out would report a permanent provider verdict as this call's own timeout, and the remedies a timeout invites — retry, a longer deadline — would both be wrong.
See https://replicate.com/docs/reference/http, https://replicate.com/docs/topics/predictions/lifecycle, and each model's API schema.
Index ¶
Constants ¶
const ( ImageRequestExtensionKey = Provider + "/image_request" SpeechRequestExtensionKey = Provider + "/speech_request" ImageResponseExtensionKey = Provider + "/image_response" SpeechResponseExtensionKey = Provider + "/speech_response" DefaultBaseURL = "https://api.replicate.com/v1" DefaultPollInterval = time.Second DefaultImagePollTimeout = 3 * time.Minute DefaultSpeechPollTimeout = 5 * time.Minute )
const ( ModelFluxSchnell = "black-forest-labs/flux-schnell" ModelFluxDev = "black-forest-labs/flux-dev" ModelFluxPro = "black-forest-labs/flux-pro" ModelFlux11Pro = "black-forest-labs/flux-1.1-pro" ModelFlux11ProUltra = "black-forest-labs/flux-1.1-pro-ultra" ModelFluxKontextPro = "black-forest-labs/flux-kontext-pro" ModelFluxKontextMax = "black-forest-labs/flux-kontext-max" ModelIdeogramV2 = "ideogram-ai/ideogram-v2" ModelIdeogramV2Turbo = "ideogram-ai/ideogram-v2-turbo" )
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"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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" )
The vocabulary is closed because it decides how a prediction's output is read. Guessing between a single URI and a list would either drop results or misreport one as many, so the shape is declared rather than inferred.
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(ctx context.Context, config ImageModelConfig) (*ImageModel, 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
type SpeechModel ¶ added in v0.41.0
type SpeechModel struct {
// contains filtered or unexported fields
}
SpeechModel 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 NewSpeechModel ¶ added in v0.41.0
func NewSpeechModel(ctx context.Context, config SpeechModelConfig) (*SpeechModel, error)
type SpeechModelConfig ¶ added in v0.41.0
type SpeechModelConfig struct {
APIKey string
DefaultOptions speech.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 (SpeechModelConfig) Validate ¶ added in v0.41.0
func (s SpeechModelConfig) Validate() error
Source Files