api

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: May 28, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnauthorized is returned when the API rejects the request due to an invalid or missing API key.
	ErrUnauthorized = errors.New("unauthorized: invalid or missing API key")
	// ErrNoAPIKey is returned when no API key is present in the local configuration.
	ErrNoAPIKey = errors.New("no API key configured")
)

Functions

func IsAuthError 

func IsAuthError(err error) bool

IsAuthError checks if an API error is an authentication error.

func NewUUID 

func NewUUID() string

NewUUID generates a new UUIDv4 for task requests.

func PollResults 

func PollResults[T any](ctx context.Context, client Client, taskUUID string, interval time.Duration, verbose bool, parse func(json.RawMessage) (T, bool)) ([]T, error)

PollResults polls for generic results from a task.

Types

type APIError 

type APIError struct {
	Code          string          `json:"code"`
	Message       string          `json:"message"`
	RawParameter  json.RawMessage `json:"parameter,omitempty"`
	Type          string          `json:"type,omitempty"`
	Documentation string          `json:"documentation,omitempty"`
	TaskUUID      string          `json:"taskUUID,omitempty"`
	AllowedValues []any           `json:"allowedValues,omitempty"`
}

APIError represents an error returned by the API.

func (APIError) Error 

func (e APIError) Error() string

func (APIError) Parameter 

func (e APIError) Parameter() string

Parameter returns the parameter field as a string, handling both string and array forms from the API.

type APIResponse 

type APIResponse struct {
	Data   []json.RawMessage `json:"data"`
	Errors []APIError        `json:"errors,omitempty"`
}

APIResponse is the top-level response from the Runware API.

type AccountResult 

type AccountResult struct {
	TaskType         TaskType     `json:"taskType"`
	TaskUUID         string       `json:"taskUUID"`
	OrganizationUUID string       `json:"organizationUUID"`
	OrganizationName string       `json:"organizationName"`
	Balance          float64      `json:"balance"`
	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       string         `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  string   `json:"taskUUID"`
	Status    string   `json:"status,omitempty"`
	AudioUUID string   `json:"audioUUID,omitempty"`
	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 interface {
	Ping(ctx context.Context) (*PingResult, error)
	ImageInference(ctx context.Context, req *ImageInferenceRequest) ([]ImageInferenceResult, error)
	VideoInference(ctx context.Context, req *VideoInferenceRequest) ([]VideoInferenceResult, error)
	AudioInference(ctx context.Context, req *AudioInferenceRequest) ([]AudioInferenceResult, error)
	TextInference(ctx context.Context, req *TextInferenceRequest) ([]TextInferenceResult, error)
	GetResponse(ctx context.Context, taskUUID string) ([]json.RawMessage, error)
	AccountDetails(ctx context.Context) (*AccountResult, error)
	ModelSearch(ctx context.Context, req *ModelSearchRequest) (*ModelSearchResponse, error)
	// Raw sends arbitrary tasks and returns the raw response. Useful for --dry-run previewing.
	Raw(ctx context.Context, tasks []any) (*APIResponse, error)
}

Client is the interface for interacting with the Runware API.

type DeliveryMethod 

type DeliveryMethod string

DeliveryMethod specifies how task results are delivered. 

const DeliveryMethodAsync DeliveryMethod = "async"

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 string   `json:"taskUUID"`
}

GetResponseRequest is used to poll for async task results.

type ImageInferenceRequest 

type ImageInferenceRequest struct {
	TaskType       TaskType     `json:"taskType"`
	TaskUUID       string       `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  string   `json:"taskUUID"`
	ImageUUID string   `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"`
	HeroImage            string   `json:"heroImage"`
	Category             string   `json:"category"`
	Private              bool     `json:"private"`
	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 ModelSearchRequest 

type ModelSearchRequest struct {
	TaskType     TaskType `json:"taskType"`
	TaskUUID     string   `json:"taskUUID"`
	Search       string   `json:"search,omitempty"`
	Category     string   `json:"category,omitempty"`
	Architecture string   `json:"architecture,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     string        `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 PingResult 

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

PingResult is the response from a ping task.

type RestClient 

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

RestClient implements Client using the Runware REST API.

func NewClient 

func NewClient(apiKey, baseURL string, verbose bool) *RestClient

NewClient creates a new REST API client.

func (*RestClient) AccountDetails 

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

AccountDetails fetches account information.

func (*RestClient) AudioInference 

func (c *RestClient) AudioInference(ctx context.Context, req *AudioInferenceRequest) ([]AudioInferenceResult, error)

AudioInference submits an audio inference task.

func (*RestClient) GetResponse 

func (c *RestClient) GetResponse(ctx context.Context, taskUUID string) ([]json.RawMessage, error)

GetResponse polls for async task results.

func (*RestClient) ImageInference 

func (c *RestClient) ImageInference(ctx context.Context, req *ImageInferenceRequest) ([]ImageInferenceResult, error)

ImageInference runs an image inference task.

func (*RestClient) ModelSearch 

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

ModelSearch searches for available models.

func (*RestClient) Ping 

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

Ping checks API connectivity.

func (*RestClient) Raw 

func (c *RestClient) Raw(ctx context.Context, tasks []any) (*APIResponse, error)

Raw sends arbitrary tasks and returns the raw response.

func (*RestClient) TextInference 

func (c *RestClient) TextInference(ctx context.Context, req *TextInferenceRequest) ([]TextInferenceResult, error)

TextInference runs a text inference task.

func (*RestClient) VideoInference 

func (c *RestClient) VideoInference(ctx context.Context, req *VideoInferenceRequest) ([]VideoInferenceResult, error)

VideoInference submits a video inference task. Video generation is async: the API returns immediately and results are polled via GetResponse.

type TaskType 

type TaskType string

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

type TextInferenceRequest 

type TextInferenceRequest struct {
	TaskType      TaskType     `json:"taskType"`
	TaskUUID      string       `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     string             `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       string         `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  string   `json:"taskUUID"`
	Status    string   `json:"status,omitempty"`
	VideoUUID string   `json:"videoUUID,omitempty"`
	VideoURL  string   `json:"videoURL,omitempty"`
	MediaUUID string   `json:"mediaUUID,omitempty"`
	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

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.