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 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. Downloads allow the configured endpoint origin and HTTPS replicate.delivery hosts on the standard port. Every redirect is checked; credentials are removed across origins. A supplied HTTP client keeps its redirect policy.
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 = "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 )
Exported identifiers keep provider-owned names and defaults out of caller literals.
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"
)
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(_ context.Context, config ImageModelConfig) (*ImageModel, error)
NewImageModel rejects an invalid provider binding before the first image call.
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
}
ImageModelConfig binds provider access and defaults shared by every image call.
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(_ context.Context, config SpeechModelConfig) (*SpeechModel, error)
NewSpeechModel rejects an invalid provider binding before the first speech call.
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
}
SpeechModelConfig binds provider access and defaults shared by every speech call.
func (SpeechModelConfig) Validate ¶ added in v0.41.0
func (s SpeechModelConfig) Validate() error
Source Files