api

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrModelRequired = errors.New("model is required")

ErrModelRequired is returned by Run when the model argument is empty.

Functions

This section is empty.

Types

type APIKeyInfo added in v0.7.0 

type APIKeyInfo struct {
	Name        string    `json:"name"`
	APIKey      string    `json:"apiKey"`
	Description string    `json:"description,omitempty"`
	Enabled     bool      `json:"enabled"`
	CreatedAt   time.Time `json:"createdAt"`
	LastUsedAt  time.Time `json:"lastUsedAt,omitempty"`
	Requests    int       `json:"requests,omitempty"`
}

APIKeyInfo describes a single API key on the account.

type AccountManagementRequest added in v0.7.0 

type AccountManagementRequest struct {
	TaskType  TaskType  `json:"taskType"`
	TaskUUID  uuid.UUID `json:"taskUUID"`
	Operation string    `json:"operation"`
}

AccountManagementRequest is the request payload for the accountManagement task.

type AccountResult 

type AccountResult struct {
	TaskType         TaskType     `json:"taskType"`
	TaskUUID         uuid.UUID    `json:"taskUUID"`
	OrganizationUUID uuid.UUID    `json:"organizationUUID"`
	OrganizationName string       `json:"organizationName"`
	AIRSource        string       `json:"AIRSource,omitempty"`
	Balance          float64      `json:"balance"`
	Team             []TeamMember `json:"team,omitempty"`
	APIKeys          []APIKeyInfo `json:"apiKeys,omitempty"`
	Usage            AccountUsage `json:"usage"`
}

AccountResult is the response from accountManagement getDetails.

type AccountUsage 

type AccountUsage struct {
	Total      UsagePeriod `json:"total"`
	Today      UsagePeriod `json:"today"`
	Last7Days  UsagePeriod `json:"last7Days"`
	Last30Days UsagePeriod `json:"last30Days"`
}

type AudioInferenceRequest 

type AudioInferenceRequest struct {
	TaskType       TaskType       `json:"taskType"`
	TaskUUID       uuid.UUID      `json:"taskUUID"`
	Model          string         `json:"model"`
	PositivePrompt string         `json:"positivePrompt,omitempty"`
	Duration       float64        `json:"duration"`
	NumberResults  int            `json:"numberResults"`
	OutputFormat   OutputFormat   `json:"outputFormat,omitempty"`
	DeliveryMethod DeliveryMethod `json:"deliveryMethod,omitempty"`
	IncludeCost    bool           `json:"includeCost,omitempty"`
	AudioSettings  *AudioSettings `json:"audioSettings,omitempty"`
}

AudioInferenceRequest contains fields for the audioInference task type.

type AudioInferenceResult 

type AudioInferenceResult struct {
	TaskType  TaskType  `json:"taskType"`
	TaskUUID  uuid.UUID `json:"taskUUID"`
	Status    string    `json:"status,omitempty"`
	AudioUUID uuid.UUID `json:"audioUUID"`
	AudioURL  string    `json:"audioURL,omitempty"`
	Cost      float64   `json:"cost,omitempty"`
}

AudioInferenceResult is a single audio result from the API.

type AudioSettings 

type AudioSettings struct {
	SampleRate int `json:"sampleRate,omitempty"`
	Bitrate    int `json:"bitrate,omitempty"`
}

AudioSettings configures technical audio quality parameters.

type Client 

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

Client provides business-logic methods for the Runware API. It delegates wire-level communication to the injected Transport.

func NewClient 

func NewClient(t transport.Transport, logger *slog.Logger) *Client

NewClient creates a Client backed by the given transport.

func (*Client) AccountDetails 

func (c *Client) AccountDetails(ctx context.Context) (*AccountResult, error)

AccountDetails fetches account information.

func (*Client) ModelSearch 

func (c *Client) ModelSearch(ctx context.Context, req ModelSearchRequest) (*ModelSearchResponse, error)

ModelSearch searches for models on the Runware platform.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) (*PingResult, error)

Ping checks API connectivity.

func (*Client) Poll added in v0.8.0 

func (c *Client) Poll(ctx context.Context, taskID uuid.UUID, interval time.Duration, onProgress func(int)) ([]json.RawMessage, error)

Poll polls for async task results using the getResponse task type. It blocks until at least one result with status "success" is returned, the context is cancelled, or a fatal API/auth error occurs.

onProgress is called with the reported progress percentage (0–100) each time a "processing" status item is received. It may be nil.

func (*Client) Run added in v0.8.0 

func (c *Client) Run(ctx context.Context, model string, args []string, opts RunOptions) ([]json.RawMessage, error)

Run executes the full inference lifecycle for the given model.

model is the AIR identifier of the model to run (e.g. "runware:101@1"). args is a slice of key=value strings (e.g. ["positivePrompt=hello", "width=1024"]). They are parsed against the model's fetched JSON Schema so that type coercion (string vs number vs bool) is schema-driven rather than best-effort. System fields (taskType, taskUUID, deliveryMethod) are injected automatically; callers must not include them in rawArgs.

For async delivery Run polls until a success result is received or the context is cancelled. For sync delivery the submit response is returned directly.

type DeliveryMethod 

type DeliveryMethod string

DeliveryMethod specifies how task results are delivered. 

const (
	DeliveryMethodAsync DeliveryMethod = "async"
	DeliveryMethodSync  DeliveryMethod = "sync"
)

type FrameImage 

type FrameImage struct {
	InputImage string `json:"inputImage"`
	Frame      any    `json:"frame"` // "first", "last", or int
}

FrameImage constrains a specific frame with an input image.

type GetResponseRequest 

type GetResponseRequest struct {
	TaskType TaskType  `json:"taskType"`
	TaskUUID uuid.UUID `json:"taskUUID"`
}

GetResponseRequest is used to poll for async task results.

type ImageInferenceRequest 

type ImageInferenceRequest struct {
	TaskType       TaskType     `json:"taskType"`
	TaskUUID       uuid.UUID    `json:"taskUUID"`
	PositivePrompt string       `json:"positivePrompt"`
	NegativePrompt string       `json:"negativePrompt,omitempty"`
	Model          string       `json:"model"`
	Width          int          `json:"width"`
	Height         int          `json:"height"`
	Steps          int          `json:"steps,omitempty"`
	NumberResults  int          `json:"numberResults"`
	CFGScale       float64      `json:"CFGScale,omitempty"`
	Scheduler      string       `json:"scheduler,omitempty"`
	Seed           int64        `json:"seed,omitempty"`
	OutputFormat   OutputFormat `json:"outputFormat,omitempty"`
	InputImage     string       `json:"inputImage,omitempty"`
	Strength       float64      `json:"strength,omitempty"`
	MaskImage      string       `json:"maskImage,omitempty"`
}

ImageInferenceRequest contains fields for the imageInference task type.

type ImageInferenceResult 

type ImageInferenceResult struct {
	TaskType  TaskType  `json:"taskType"`
	TaskUUID  uuid.UUID `json:"taskUUID"`
	ImageUUID uuid.UUID `json:"imageUUID"`
	ImageURL  string    `json:"imageURL"`
	Seed      int64     `json:"seed"`
}

ImageInferenceResult is a single image result from the API.

type Message 

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message represents a single message in a text inference conversation.

type ModelResult 

type ModelResult struct {
	Name                 string   `json:"name"`
	AIR                  string   `json:"air"`
	Tags                 []string `json:"tags"`
	ImageURL             string   `json:"imageURL"`
	ThumbnailURL         string   `json:"thumbnailURL"`
	Category             string   `json:"category"`
	Private              bool     `json:"private"`
	BaseModel            string   `json:"baseModel,omitempty"`
	Version              string   `json:"version"`
	Architecture         string   `json:"architecture"`
	NSFWLevel            int      `json:"nsfwLevel"`
	Type                 string   `json:"type,omitempty"`
	DefaultWeight        float64  `json:"defaultWeight,omitempty"`
	DefaultWidth         int      `json:"defaultWidth,omitempty"`
	DefaultHeight        int      `json:"defaultHeight,omitempty"`
	DefaultSteps         int      `json:"defaultSteps,omitempty"`
	DefaultScheduler     string   `json:"defaultScheduler,omitempty"`
	DefaultCFG           float64  `json:"defaultCFG,omitempty"`
	DefaultStrength      float64  `json:"defaultStrength,omitempty"`
	PositiveTriggerWords string   `json:"positiveTriggerWords,omitempty"`
	NegativeTriggerWords string   `json:"negativeTriggerWords,omitempty"`
}

ModelResult is a single model from the search results.

type ModelSchema added in v0.7.0 

type ModelSchema struct {
	RequestSchema  json.RawMessage `json:"requestSchema"`
	ResponseSchema json.RawMessage `json:"responseSchema"`
	Documentation  string          `json:"documentation"`
}

ModelSchema is the response from the schema resolve endpoint.

func FetchModelSchema added in v0.7.0 

func FetchModelSchema(ctx context.Context, air string) (*ModelSchema, error)

FetchModelSchema retrieves the request and response JSON Schema for the given AIR identifier from the Runware schema service. This endpoint is unauthenticated and separate from the inference API transport.

func (ModelSchema) MarshalYAML added in v0.7.0 

func (s ModelSchema) MarshalYAML() (any, error)

MarshalYAML converts ModelSchema to a form the YAML encoder can handle. json.RawMessage fields are []byte, which would otherwise be base64-encoded by the YAML encoder. Unmarshaling them to any first produces native Go maps/slices that YAML can render as structured output.

type ModelSearchRequest 

type ModelSearchRequest struct {
	TaskType     TaskType  `json:"taskType"`
	TaskUUID     uuid.UUID `json:"taskUUID"`
	Search       string    `json:"search,omitempty"`
	Tags         []string  `json:"tags,omitempty"`
	Category     string    `json:"category,omitempty"`
	Type         string    `json:"type,omitempty"`
	Architecture string    `json:"architecture,omitempty"`
	Conditioning string    `json:"conditioning,omitempty"`
	Visibility   string    `json:"visibility,omitempty"`
	Limit        int       `json:"limit,omitempty"`
	Offset       int       `json:"offset,omitempty"`
}

ModelSearchRequest contains fields for the modelSearch task type.

type ModelSearchResponse 

type ModelSearchResponse struct {
	TaskType     TaskType      `json:"taskType"`
	TaskUUID     uuid.UUID     `json:"taskUUID"`
	Results      []ModelResult `json:"results"`
	TotalResults int           `json:"totalResults"`
}

ModelSearchResponse is the response wrapper from modelSearch.

type OutputFormat 

type OutputFormat string

OutputFormat specifies the media output format. 

const (
	OutputFormatPNG  OutputFormat = "png"
	OutputFormatJPG  OutputFormat = "jpg"
	OutputFormatJPEG OutputFormat = "jpeg"
	OutputFormatWebP OutputFormat = "webp"
	OutputFormatMP3  OutputFormat = "mp3"
	OutputFormatMP4  OutputFormat = "mp4"
	OutputFormatText OutputFormat = "text"
	OutputFormatJSON OutputFormat = "json"
)

type PingRequest added in v0.7.0 

type PingRequest struct {
	TaskType TaskType  `json:"taskType"`
	TaskUUID uuid.UUID `json:"taskUUID"`
}

PingRequest is the request payload for the ping task.

type PingResult 

type PingResult struct {
	TaskType TaskType `json:"taskType"`
	Pong     bool     `json:"pong"`
}

PingResult is the response from a ping task.

type RunOptions added in v0.8.0 

type RunOptions struct {
	// TaskType overrides the task type detected from the model schema.
	// Required when the schema is unavailable or does not encode a task type.
	TaskType string

	// DeliveryMethod overrides the delivery method resolved from the model schema.
	// Accepted values: "sync", "async". Empty means resolve from schema or payload.
	DeliveryMethod string

	// PollInterval is the interval between getResponse polls when delivery is async.
	// Defaults to 2 seconds when zero.
	PollInterval time.Duration

	// OnProgress is called with the reported progress percentage (0–100) during async
	// polling. It may be nil.
	OnProgress func(int)
}

RunOptions configures the behaviour of Client.Run.

type TaskType 

type TaskType string

TaskType identifies the Runware API task. Set by client methods; not exposed to callers.

type TeamMember added in v0.7.0 

type TeamMember struct {
	Name     string    `json:"name"`
	Email    string    `json:"email"`
	Roles    []string  `json:"roles"`
	JoinedAt time.Time `json:"joinedAt,omitempty"`
}

TeamMember is a member of the organization.

type TextInferenceRequest 

type TextInferenceRequest struct {
	TaskType      TaskType     `json:"taskType"`
	TaskUUID      uuid.UUID    `json:"taskUUID"`
	Model         string       `json:"model"`
	Messages      []Message    `json:"messages"`
	MaxTokens     int          `json:"maxTokens,omitempty"`
	Temperature   float64      `json:"temperature,omitempty"`
	TopP          float64      `json:"topP,omitempty"`
	TopK          int          `json:"topK,omitempty"`
	Seed          int64        `json:"seed,omitempty"`
	StopSequences []string     `json:"stopSequences,omitempty"`
	NumberResults int          `json:"numberResults,omitempty"`
	SystemPrompt  string       `json:"systemPrompt,omitempty"`
	OutputFormat  OutputFormat `json:"outputFormat,omitempty"`
	IncludeCost   bool         `json:"includeCost,omitempty"`
}

TextInferenceRequest contains fields for the textInference task type.

type TextInferenceResult 

type TextInferenceResult struct {
	TaskType     TaskType           `json:"taskType"`
	TaskUUID     uuid.UUID          `json:"taskUUID"`
	Text         string             `json:"text"`
	FinishReason string             `json:"finishReason,omitempty"`
	Usage        TextInferenceUsage `json:"usage"`
	Cost         float64            `json:"cost,omitempty"`
}

TextInferenceResult is a single text result from the API.

type TextInferenceUsage 

type TextInferenceUsage struct {
	InputTokens  int `json:"inputTokens,omitempty"`
	OutputTokens int `json:"outputTokens,omitempty"`
	TotalTokens  int `json:"totalTokens,omitempty"`
}

TextInferenceUsage contains token usage statistics.

type UsagePeriod 

type UsagePeriod struct {
	Credits  float64 `json:"credits"`
	Requests int     `json:"requests"`
}

type VideoInferenceRequest 

type VideoInferenceRequest struct {
	TaskType       TaskType       `json:"taskType"`
	TaskUUID       uuid.UUID      `json:"taskUUID"`
	Model          string         `json:"model"`
	PositivePrompt string         `json:"positivePrompt,omitempty"`
	NegativePrompt string         `json:"negativePrompt,omitempty"`
	Width          int            `json:"width,omitempty"`
	Height         int            `json:"height,omitempty"`
	Duration       float64        `json:"duration,omitempty"`
	Steps          int            `json:"steps,omitempty"`
	CFGScale       float64        `json:"CFGScale,omitempty"`
	Seed           int64          `json:"seed,omitempty"`
	NumberResults  int            `json:"numberResults,omitempty"`
	OutputFormat   OutputFormat   `json:"outputFormat,omitempty"`
	DeliveryMethod DeliveryMethod `json:"deliveryMethod,omitempty"`
	FrameImages    []FrameImage   `json:"frameImages,omitempty"`
	IncludeCost    bool           `json:"includeCost,omitempty"`
}

VideoInferenceRequest contains fields for the videoInference task type.

type VideoInferenceResult 

type VideoInferenceResult struct {
	TaskType  TaskType  `json:"taskType"`
	TaskUUID  uuid.UUID `json:"taskUUID"`
	Status    string    `json:"status,omitempty"`
	VideoUUID uuid.UUID `json:"videoUUID"`
	VideoURL  string    `json:"videoURL,omitempty"`
	MediaUUID uuid.UUID `json:"mediaUUID"`
	MediaURL  string    `json:"mediaURL,omitempty"`
	Seed      int64     `json:"seed,omitempty"`
	Cost      float64   `json:"cost,omitempty"`
}

VideoInferenceResult is a single video result from the API.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.