models

package
v0.6.7 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package models compatibility additions: OpenAI prior-generation and Anthropic-compatible wire types plus the router-side async stores backing responses, conversations, assistants, threads, runs and message batches.

Every record minted here carries its ID prefix (resp_, asst_, thread_, msg_, run_, batch_, conv_) so logs and clients distinguish kinds without a second lookup.

Package models defines all shared data structures for llm-router.

Index

Constants

View Source
const (
	ResponseStatusCompleted    = "completed"
	ResponseStatusFailed       = "failed"
	ResponseStatusCanceled     = "canceled"
	ResponseStatusInProgress   = "in_progress"
	ResponseStatusRequiresAct  = "requires_action"
	ResponseObjectResponse     = "response"
	ResponseObjectConversation = "conversation"
	ResponseObjectAssistant    = "assistant"
	ResponseObjectThread       = "thread"
	ResponseRoleUser           = "user"
	ResponseRoleAssistant      = "assistant"
	BatchObjectType            = "message_batch"
)

Response lifecycle statuses stored on ResponseRecord.Status.

View Source
const (
	BatchResultSucceeded = "succeeded"
	BatchResultErrored   = "errored"
	BatchResultCanceled  = "canceled"
	BatchResultExpired   = "expired"
)

Per-entry batch result types counted in BatchRequestCounts.

View Source
const (
	EndpointChatCompletions    = "chat/completions"
	EndpointAudioTranscription = "audio/transcriptions"
	EndpointAudioTranslation   = "audio/translations"
	EndpointAudioSpeech        = "audio/speech"
	EndpointImagesGenerations  = "images/generations"
	EndpointEmbeddings         = "embeddings"
	EndpointVideos             = "videos"
	// EndpointModerations names the moderation capability in model cards.
	// Request gates key on EndpointChatCompletions (every moderation
	// request names a chat-serving model); the backend capability
	// pre-check (moderate handler) decides support.
	EndpointModerations = "moderations"
	// EndpointResponses names the responses capability in model cards.
	// Responses, conversations, assistants, threads and runs execute on
	// the chat pipeline, so request gates key on
	// EndpointChatCompletions, exactly like POST /v1/messages.
	EndpointResponses = "responses"
)

Endpoint identifiers listed in ModelInfo.Endpoints. The router rejects a request when the resolved model declares Endpoints and the target endpoint is absent; an empty Endpoints list means chat/completions only (legacy plugins predate the field).

View Source
const (
	VideoStatusPending    = "pending"
	VideoStatusInProgress = "in_progress"
	VideoStatusCompleted  = "completed"
	VideoStatusFailed     = "failed"
	VideoStatusCancelled  = "cancelled"
	VideoStatusExpired    = "expired"
)

Video statuses carried by VideoGenerationResponse.Status.

View Source
const (
	DisabledByAdmin       = "admin"
	DisabledBySystem      = "system"
	DisabledByPlugin      = "plugin"
	DisabledByHealthcheck = "healthcheck"
)

Who disabled a provider or credential. Single source of truth for DisabledBy comparisons across credential, provider, and healthcheck.

View Source
const DefaultProxyPool = "auto"

DefaultProxyPool is the pool name for the router free pool.

View Source
const MaxProxyChecks = 2000

MaxProxyChecks is the highest accepted RouterConfiguration.ProxyMaxChecks.

View Source
const ProxyDataVersion = 1

ProxyDataVersion is the format version of ProxyDataBundle.

Variables

This section is empty.

Functions

func AnthropicFinishReason added in v0.3.8

func AnthropicFinishReason(reason string) string

AnthropicFinishReason maps OpenAI finish reasons to Anthropic stop reasons.

func CredentialAutomationOn added in v0.3.8

func CredentialAutomationOn(providerConfig map[string]any) bool

CredentialAutomationOn reports the provider disable_failed_credentials switch: the single master for every non-manual credential disable (single probes, detached health checks, plugin shared writes). Absent or non-boolean reads off, matching the dashboard default.

func EmbeddingBase64 added in v0.0.5

func EmbeddingBase64(values []float64) string

EmbeddingBase64 encodes a float vector as base64 float32 little-endian, the OpenAI encoding_format=base64 wire form.

func EstimateInputTokens added in v0.3.8

func EstimateInputTokens(texts []string) int

EstimateInputTokens approximates input tokens for count_tokens endpoints: 4 characters per token, minimum 1. Clients needing exact billing counts use upstream tokenizers; the router documents this heuristic in the API description.

func JoinModalities added in v0.3.8

func JoinModalities(mods []string) string

JoinModalities renders OpenRouter-style modality strings: ["text","image"] -> "text+image".

func NewAssistantID added in v0.3.8

func NewAssistantID() string

NewAssistantID mints an asst_* identifier.

func NewBatchID added in v0.3.8

func NewBatchID() string

NewBatchID mints a batch_* identifier for Anthropic message batches.

func NewConversationID added in v0.3.8

func NewConversationID() string

NewConversationID mints a conv_* identifier.

func NewModerationID added in v0.3.8

func NewModerationID() string

NewModerationID mints a modr_* identifier.

func NewResponseID added in v0.3.8

func NewResponseID() string

NewResponseID mints a resp_* identifier for response and conversation items.

func NewRunID added in v0.3.8

func NewRunID() string

NewRunID mints a run_* identifier.

func NewThreadID added in v0.3.8

func NewThreadID() string

NewThreadID mints a thread_* identifier.

func NewThreadMessageID added in v0.3.8

func NewThreadMessageID() string

NewThreadMessageID mints a msg_* identifier.

func NewVideoJobID added in v0.3.8

func NewVideoJobID(now time.Time) string

NewVideoJobID mints a router-local video job ID in the OpenRouter `gen-vid-<timestamp>-<20 alphanumerics>` format.

func NormalizeBaseURL added in v0.1.2

func NormalizeBaseURL(raw string) (string, error)

NormalizeBaseURL trims raw and requires an http(s) URL without a trailing slash. Single source of truth for base_url validation across provider CRUD and the custom backend.

func SpeechContentType added in v0.0.5

func SpeechContentType(format string) string

SpeechContentType maps a speech format to its wire Content-Type.

func ValidVideoStatus added in v0.3.8

func ValidVideoStatus(status string) bool

ValidVideoStatus reports whether status is a known video job status.

func VideoContentType added in v0.3.8

func VideoContentType(contentType string) string

VideoContentType defaults empty content types to video/mp4.

Types

type AdminUser

type AdminUser struct {
	Username     string    `json:"username"`
	PasswordHash string    `json:"password_hash"`
	CreatedAt    time.Time `json:"created_at"`
}

AdminUser is the dashboard operator account.

type AnthropicCacheControl added in v0.3.8

type AnthropicCacheControl struct {
	Type string `json:"type,omitempty"`
	TTL  string `json:"ttl,omitempty"`
}

AnthropicCacheControl marks a block for prompt caching.

type AnthropicCompleteRequest added in v0.3.8

type AnthropicCompleteRequest struct {
	Model             string   `json:"model"`
	Prompt            string   `json:"prompt"`
	MaxTokensToSample int      `json:"max_tokens_to_sample"`
	StopSequences     []string `json:"stop_sequences,omitempty"`
	Stream            bool     `json:"stream,omitempty"`
	Temperature       *float64 `json:"temperature,omitempty"`
	TopP              *float64 `json:"top_p,omitempty"`
	TopK              *int     `json:"top_k,omitempty"`
}

AnthropicCompleteRequest is the POST /v1/complete legacy body.

func (*AnthropicCompleteRequest) ToMessageRequest added in v0.3.8

func (r *AnthropicCompleteRequest) ToMessageRequest() *AnthropicMessageRequest

ToMessageRequest wraps the completion as a single-turn messages request.

type AnthropicCompleteResponse added in v0.3.8

type AnthropicCompleteResponse struct {
	ID         string `json:"id"`
	Type       string `json:"type"`
	Completion string `json:"completion"`
	StopReason string `json:"stop_reason"`
	Model      string `json:"model"`
}

AnthropicCompleteResponse is the /v1/complete answer.

type AnthropicContentBlock added in v0.3.8

type AnthropicContentBlock struct {
	Type         string                  `json:"type"`
	Text         string                  `json:"text,omitempty"`
	Thinking     string                  `json:"thinking,omitempty"`
	Source       *AnthropicContentSource `json:"source,omitempty"`
	ID           string                  `json:"id,omitempty"`
	Name         string                  `json:"name,omitempty"`
	Input        json.RawMessage         `json:"input,omitempty"`
	ToolUseID    string                  `json:"tool_use_id,omitempty"`
	Content      json.RawMessage         `json:"content,omitempty"`
	IsError      bool                    `json:"is_error,omitempty"`
	CacheControl *AnthropicCacheControl  `json:"cache_control,omitempty"`
}

AnthropicContentBlock is one typed content block in a message, tool definition, or tool result. CacheControl is accepted on every block and forwarded as a caching hint; document blocks are refused at the edge (the chat pipeline has no document part).

func AnthropicBlocks added in v0.3.8

func AnthropicBlocks(raw json.RawMessage) ([]AnthropicContentBlock, error)

AnthropicBlocks parses a polymorphic Anthropic content field (plain string or block array) into blocks.

type AnthropicContentSource added in v0.3.8

type AnthropicContentSource struct {
	Type      string `json:"type"`
	MediaType string `json:"media_type,omitempty"`
	Data      string `json:"data,omitempty"`
	URL       string `json:"url,omitempty"`
}

AnthropicContentSource is an image or document source.

type AnthropicMessage added in v0.3.8

type AnthropicMessage struct {
	ID           string           `json:"id"`
	Type         string           `json:"type"`
	Role         string           `json:"role"`
	Model        string           `json:"model"`
	Content      []map[string]any `json:"content"`
	StopReason   string           `json:"stop_reason"`
	StopSequence *string          `json:"stop_sequence"`
	Usage        AnthropicUsage   `json:"usage"`
}

AnthropicMessage is the non-stream /v1/messages answer.

func AnthropicMessageFromChat added in v0.3.8

func AnthropicMessageFromChat(resp *ChatCompletionResponse, model string) *AnthropicMessage

AnthropicMessageFromChat renders the chat completion as an Anthropic message.

type AnthropicMessageRequest added in v0.3.8

type AnthropicMessageRequest struct {
	Model         string                   `json:"model"`
	MaxTokens     int                      `json:"max_tokens"`
	System        json.RawMessage          `json:"system,omitempty"`
	Messages      []json.RawMessage        `json:"messages"`
	Tools         []AnthropicTool          `json:"tools,omitempty"`
	ToolChoice    *AnthropicToolChoice     `json:"tool_choice,omitempty"`
	Thinking      *AnthropicThinkingConfig `json:"thinking,omitempty"`
	Temperature   *float64                 `json:"temperature,omitempty"`
	TopP          *float64                 `json:"top_p,omitempty"`
	TopK          *int                     `json:"top_k,omitempty"`
	StopSequences []string                 `json:"stop_sequences,omitempty"`
	Stream        bool                     `json:"stream,omitempty"`
	Metadata      *AnthropicMetadata       `json:"metadata,omitempty"`
}

AnthropicMessageRequest is the POST /v1/messages body. System accepts a string or text blocks; messages accept user/assistant roles with string or block content; TopK is accepted (no chat equivalent, documented).

func (*AnthropicMessageRequest) ToChat added in v0.3.8

ToChat converts the Anthropic request into the router's chat shape. Document blocks are refused: the chat pipeline has no document part. Cache-control, top_k and top-level thinking budgets are accepted and documented; they carry no mapping.

type AnthropicMetadata added in v0.3.8

type AnthropicMetadata struct {
	UserID string `json:"user_id,omitempty"`
}

AnthropicMetadata carries request metadata; UserID maps to chat User.

type AnthropicModelEntry added in v0.3.8

type AnthropicModelEntry struct {
	Type        string `json:"type"`
	ID          string `json:"id"`
	DisplayName string `json:"display_name,omitempty"`
	CreatedAt   string `json:"created_at,omitempty"`
}

AnthropicModelEntry is one model card in the Anthropic models shape.

type AnthropicModelListResponse added in v0.3.8

type AnthropicModelListResponse struct {
	Data    []AnthropicModelEntry `json:"data"`
	HasMore bool                  `json:"has_more"`
	FirstID *string               `json:"first_id"`
	LastID  *string               `json:"last_id"`
}

AnthropicModelListResponse is the Anthropic GET /v1/models wire response.

type AnthropicThinkingConfig added in v0.3.8

type AnthropicThinkingConfig struct {
	Type         string `json:"type"`
	BudgetTokens *int   `json:"budget_tokens,omitempty"`
}

AnthropicThinkingConfig is the top-level thinking configuration. Enabled thinking with a budget maps assistant thinking blocks through ReasoningContent; the budget itself is accepted and documented.

type AnthropicTokenCount added in v0.3.8

type AnthropicTokenCount struct {
	InputTokens int `json:"input_tokens"`
}

AnthropicTokenCount is the /v1/messages/count_tokens answer.

type AnthropicTool added in v0.3.8

type AnthropicTool struct {
	Name         string                 `json:"name"`
	Description  string                 `json:"description,omitempty"`
	InputSchema  map[string]any         `json:"input_schema"`
	CacheControl *AnthropicCacheControl `json:"cache_control,omitempty"`
}

AnthropicTool is one tool definition.

type AnthropicToolChoice added in v0.3.8

type AnthropicToolChoice struct {
	Type                   string `json:"type"`
	Name                   string `json:"name,omitempty"`
	DisableParallelToolUse bool   `json:"disable_parallel_tool_use,omitempty"`
}

AnthropicToolChoice is the tool_choice selector.

type AnthropicUsage added in v0.3.8

type AnthropicUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
}

AnthropicUsage carries token usage for messages.

type Assistant added in v0.3.8

type Assistant struct {
	ID             string            `json:"id"`
	Object         string            `json:"object"`
	CreatedAt      int64             `json:"created_at"`
	Model          string            `json:"model"`
	Name           string            `json:"name,omitempty"`
	Description    string            `json:"description,omitempty"`
	Instructions   string            `json:"instructions,omitempty"`
	Tools          []json.RawMessage `json:"tools,omitempty"`
	ResponseFormat json.RawMessage   `json:"response_format,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

Assistant is a stored response preset plus chat pipeline defaults.

type AssistantRequest added in v0.3.8

type AssistantRequest struct {
	Model          ModelId           `json:"model,omitempty"`
	Name           string            `json:"name,omitempty"`
	Description    string            `json:"description,omitempty"`
	Instructions   string            `json:"instructions,omitempty"`
	Tools          []json.RawMessage `json:"tools,omitempty"`
	ResponseFormat json.RawMessage   `json:"response_format,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

AssistantRequest is the create/update body for assistants.

type AuthFlowResult

type AuthFlowResult struct {
	Render      []*UINode      `json:"render,omitempty"`
	RedirectURL string         `json:"redirect_url,omitempty"`
	Credentials map[string]any `json:"credentials,omitempty"`
}

AuthFlowResult is one of the three auth_step/auth_initiate outcomes, discriminated by which field is set.

type AuthStepInput

type AuthStepInput struct {
	Action string         `json:"action"`
	Values map[string]any `json:"values"`
	FlowID string         `json:"flow_id,omitempty"`
}

AuthStepInput is the submit payload for auth_step.

type BatchCreateRequest added in v0.3.8

type BatchCreateRequest struct {
	Requests []BatchEntry `json:"requests"`
}

BatchCreateRequest is the POST /v1/messages/batches body.

type BatchEntry added in v0.3.8

type BatchEntry struct {
	CustomID string          `json:"custom_id"`
	Params   json.RawMessage `json:"params"`
}

BatchEntry is one request inside a batch create.

type BatchInfo added in v0.3.8

type BatchInfo struct {
	ID               string             `json:"id"`
	Type             string             `json:"type"`
	ProcessingStatus string             `json:"processing_status"`
	RequestCounts    BatchRequestCounts `json:"request_counts"`
	CreatedAt        string             `json:"created_at"`
	ExpiresAt        string             `json:"expires_at,omitempty"`
	EndedAt          *string            `json:"ended_at,omitempty"`
	ResultsURL       string             `json:"results_url,omitempty"`
}

BatchInfo is the served batch object.

type BatchRecord added in v0.3.8

type BatchRecord struct {
	ID        string            `json:"id"`
	Model     ModelId           `json:"model"`
	Status    string            `json:"status"`
	Entries   []BatchEntry      `json:"entries,omitempty"`
	Results   []BatchResultLine `json:"results,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
	EndedAt   *time.Time        `json:"ended_at,omitempty"`
}

BatchRecord persists one batch: the entries plus per-entry results.

func (*BatchRecord) BatchResults added in v0.3.8

func (b *BatchRecord) BatchResults() string

BatchResults renders stored results as JSONL lines.

func (*BatchRecord) ToBatchInfo added in v0.3.8

func (b *BatchRecord) ToBatchInfo(resultsURL string) *BatchInfo

ToBatchInfo renders the wire batch object. ResultsURL points at the router-local results endpoint when results exist.

type BatchRequestCounts added in v0.3.8

type BatchRequestCounts struct {
	Processing int `json:"processing"`
	Succeeded  int `json:"succeeded"`
	Errored    int `json:"errored"`
	Canceled   int `json:"canceled"`
	Expired    int `json:"expired"`
}

BatchRequestCounts tracks batch request states.

type BatchResultLine added in v0.3.8

type BatchResultLine struct {
	CustomID string          `json:"custom_id"`
	Result   json.RawMessage `json:"result"`
}

BatchResultLine is one JSONL result line.

type ChatCompletionChoice

type ChatCompletionChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
	Logprobs     any         `json:"logprobs,omitempty"`
}

type ChatCompletionRequest

type ChatCompletionRequest struct {
	Model               ModelId        `json:"model" example:"openai/gpt-4o"`
	Messages            []ChatMessage  `json:"messages"`
	Tools               []ChatTool     `json:"tools,omitempty"`
	ToolChoice          any            `json:"tool_choice,omitempty"`
	ParallelToolCalls   *bool          `json:"parallel_tool_calls,omitempty"`
	Stream              bool           `json:"stream,omitempty" example:"false"`
	StreamOptions       *StreamOptions `json:"stream_options,omitempty"`
	MaxTokens           int            `json:"max_tokens,omitempty" example:"1000"`
	MaxCompletionTokens *int           `json:"max_completion_tokens,omitempty"`
	Temperature         float64        `json:"temperature,omitempty" example:"0.7"`
	TopP                float64        `json:"top_p,omitempty" example:"1.0"`
	N                   *int           `json:"n,omitempty"`
	// Stop is a string, a list of strings, or nil (polymorphic by design).
	Stop             any      `json:"stop,omitempty"`
	Seed             *int64   `json:"seed,omitempty"`
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	PresencePenalty  *float64 `json:"presence_penalty,omitempty"`
	Logprobs         *bool    `json:"logprobs,omitempty"`
	TopLogprobs      *int     `json:"top_logprobs,omitempty"`
	// ResponseFormat is a free-form object (json_object, json_schema, ...).
	ResponseFormat  any     `json:"response_format,omitempty"`
	User            *string `json:"user,omitempty"`
	ServiceTier     *string `json:"service_tier,omitempty"`
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
	Verbosity       *string `json:"verbosity,omitempty"`
	// RandomSeed is the Mistral `random_seed` alias for Seed.
	RandomSeed *int64 `json:"random_seed,omitempty"`
	// Options carries Ollama `options{temperature,top_p,seed,stop,num_predict,num_ctx,top_k}`.
	Options map[string]any `json:"options,omitempty"`
	// Format carries the Ollama `format` alias for ResponseFormat.
	Format any `json:"format,omitempty"`
	// Think carries the Ollama `think` flag (accepted, reasoning stays model-driven).
	Think any `json:"think,omitempty"`
	// KeepAlive carries the Ollama `keep_alive` hint (accepted, ignored).
	KeepAlive any `json:"keep_alive,omitempty"`
	// Reasoning carries the OpenRouter `reasoning{effort,max_tokens}` envelope.
	Reasoning *ReasoningConfig `json:"reasoning,omitempty"`
	// PromptCacheKey is accepted and ignored (provider-side caching hint).
	PromptCacheKey any `json:"prompt_cache_key,omitempty"`
	// Guardrails is accepted and ignored (Mistral-side safety config).
	Guardrails any `json:"guardrails,omitempty"`
}

ChatCompletionRequest is the incoming /v1/chat/completions body.

Alias fields translate derivative clients without new paths: RandomSeed (Mistral `random_seed`), Options/Format/Think/KeepAlive (Ollama `options`, `format`, `think`, `keep_alive`), Reasoning (OpenRouter `reasoning{effort,max_tokens}`), PromptCacheKey/Guardrails (accepted and ignored). NormalizeAliases folds every mapped alias into its canonical field; unknown fields are ignored by the JSON decoder.

func (*ChatCompletionRequest) NormalizeAliases added in v0.3.8

func (r *ChatCompletionRequest) NormalizeAliases()

NormalizeAliases folds derivative-client alias fields into their canonical counterparts. Canonical fields win on conflict; unmapped aliases stay accepted and ignored.

type ChatCompletionResponse

type ChatCompletionResponse struct {
	ID                string                 `json:"id"`
	Object            string                 `json:"object"`
	Created           int64                  `json:"created"`
	Model             string                 `json:"model"`
	Choices           []ChatCompletionChoice `json:"choices"`
	Usage             ChatCompletionUsage    `json:"usage"`
	SystemFingerprint *string                `json:"system_fingerprint,omitempty"`
	ServiceTier       *string                `json:"service_tier,omitempty"`
}

ChatCompletionResponse mirrors the OpenAI response schema.

type ChatCompletionUsage

type ChatCompletionUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`

	PromptTokensDetails     *PromptTokensDetails     `json:"prompt_tokens_details,omitempty"`
	CompletionTokensDetails *CompletionTokensDetails `json:"completion_tokens_details,omitempty"`
}

type ChatMessage

type ChatMessage struct {
	Role         string                   `json:"role" example:"user" enums:"system,user,assistant,tool,developer"`
	Content      string                   `json:"content,omitempty" example:"Hello, how are you?"`
	ContentParts []ChatMessageContentPart `json:"content_parts,omitempty"`
	ToolCalls    []ChatToolCall           `json:"tool_calls,omitempty"`
	ToolCallID   string                   `json:"tool_call_id,omitempty"`
	Name         string                   `json:"name,omitempty"`
	Refusal      *string                  `json:"refusal,omitempty"`
	// ReasoningContent carries chain-of-thought text exposed by reasoning
	// models (DeepSeek `reasoning_content`, Groq `reasoning`).
	ReasoningContent string `json:"reasoning_content,omitempty"`
}

ChatMessage is a single turn in a conversation.

Content carries plain-text turns. ContentParts carries vision/audio turns: on the wire both serialize as the OpenAI `content` field (string or part array); the split property exists so the generated API schema documents both shapes. Custom MarshalJSON/UnmarshalJSON own the wire mapping, so these tags serve the spec generator only.

func (ChatMessage) MarshalJSON

func (m ChatMessage) MarshalJSON() ([]byte, error)

func (ChatMessage) TextContent

func (m ChatMessage) TextContent() string

func (*ChatMessage) UnmarshalJSON

func (m *ChatMessage) UnmarshalJSON(data []byte) error

type ChatMessageContentPart

type ChatMessageContentPart struct {
	Type        string                   `json:"type,omitempty"`
	Text        string                   `json:"text,omitempty"`
	ToolUseID   string                   `json:"tool_use_id,omitempty"`
	ID          string                   `json:"id,omitempty"`
	Name        string                   `json:"name,omitempty"`
	Input       json.RawMessage          `json:"input,omitempty"`
	ImageURL    *ChatMessageImageURL     `json:"image_url,omitempty"`
	InputAudio  *ChatMessageInputAudio   `json:"input_audio,omitempty"`
	Content     []ChatMessageContentPart `json:"-"`
	ContentText string                   `json:"-"`
}

func (ChatMessageContentPart) MarshalJSON

func (p ChatMessageContentPart) MarshalJSON() ([]byte, error)

func (ChatMessageContentPart) TextContent

func (p ChatMessageContentPart) TextContent() string

func (*ChatMessageContentPart) UnmarshalJSON

func (p *ChatMessageContentPart) UnmarshalJSON(data []byte) error

type ChatMessageImageURL

type ChatMessageImageURL struct {
	URL    string `json:"url,omitempty"`
	Detail string `json:"detail,omitempty"`
}

ChatMessageImageURL is an OpenAI image_url content part. URL is either a remote http(s) URL or a data: URL carrying base64 bytes inline.

type ChatMessageInputAudio

type ChatMessageInputAudio struct {
	Data   string `json:"data,omitempty"`
	Format string `json:"format,omitempty"`
}

ChatMessageInputAudio is an OpenAI input_audio content part. Data is base64 audio, Format is wav or mp3.

type ChatTool

type ChatTool struct {
	Type        string            `json:"type,omitempty"`
	Name        string            `json:"name,omitempty"`
	Description string            `json:"description,omitempty"`
	Parameters  map[string]any    `json:"parameters,omitempty"`
	InputSchema map[string]any    `json:"input_schema,omitempty"`
	Function    *ChatToolFunction `json:"function,omitempty"`
	Strict      *bool             `json:"strict,omitempty"`
}

type ChatToolCall

type ChatToolCall struct {
	ID           string                 `json:"id,omitempty"`
	Type         string                 `json:"type,omitempty"`
	Function     ChatToolFunction       `json:"function"`
	ExtraContent map[string]interface{} `json:"extra_content,omitempty"`
}

type ChatToolFunction

type ChatToolFunction struct {
	Name        string         `json:"name,omitempty"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Arguments   string         `json:"arguments,omitempty"`
	Strict      *bool          `json:"strict,omitempty"`
}

type CompletionChoice added in v0.3.8

type CompletionChoice struct {
	Index        int    `json:"index"`
	Text         string `json:"text"`
	FinishReason string `json:"finish_reason"`
	Logprobs     any    `json:"logprobs,omitempty"`
}

CompletionChoice is one text completion choice.

type CompletionRequest added in v0.3.8

type CompletionRequest struct {
	Model          ModelId         `json:"model"`
	Prompt         []string        `json:"-"`
	RawPrompt      json.RawMessage `json:"-"`
	Suffix         string          `json:"suffix,omitempty"`
	MaxTokens      int             `json:"max_tokens,omitempty"`
	Temperature    float64         `json:"temperature,omitempty"`
	TopP           float64         `json:"top_p,omitempty"`
	N              *int            `json:"n,omitempty"`
	BestOf         *int            `json:"best_of,omitempty"`
	Echo           *bool           `json:"echo,omitempty"`
	Logprobs       *int            `json:"logprobs,omitempty"`
	Stop           any             `json:"stop,omitempty"`
	Stream         bool            `json:"stream,omitempty"`
	Seed           *int64          `json:"seed,omitempty"`
	RandomSeed     *int64          `json:"random_seed,omitempty"`
	User           *string         `json:"user,omitempty"`
	System         string          `json:"system,omitempty"`
	Images         []string        `json:"images,omitempty"`
	Raw            *bool           `json:"raw,omitempty"`
	Think          any             `json:"think,omitempty"`
	Options        map[string]any  `json:"options,omitempty"`
	Format         any             `json:"format,omitempty"`
	PromptCacheKey any             `json:"prompt_cache_key,omitempty"`
}

CompletionRequest is the incoming POST /v1/completions body. Prompt is polymorphic (string, list of strings, token arrays are refused as in embeddings). Alias fields translate derivative clients: System (Ollama `system`), Suffix doubling as Mistral FIM suffix, Images/Raw/Think/Options (Ollama generate fields), RandomSeed (Mistral `random_seed`), Format (Ollama `format` alias for logit_bias-free response shaping, accepted). ToChat maps the request onto the chat pipeline.

func (*CompletionRequest) NormalizeAliases added in v0.3.8

func (r *CompletionRequest) NormalizeAliases()

NormalizeAliases folds derivative-client aliases into canonical fields.

func (*CompletionRequest) ToChat added in v0.3.8

ToChat maps the completion onto a single-turn chat request: optional system message, user turn of prompt plus suffix. Images attach as image parts when present.

func (*CompletionRequest) UnmarshalJSON added in v0.3.8

func (r *CompletionRequest) UnmarshalJSON(raw []byte) error

UnmarshalJSON accepts prompt as a string or a list of strings. Token-ID arrays are refused: the router has no tokenizer to decode them.

type CompletionResponse added in v0.3.8

type CompletionResponse struct {
	ID      string              `json:"id"`
	Object  string              `json:"object"`
	Created int64               `json:"created"`
	Model   string              `json:"model"`
	Choices []CompletionChoice  `json:"choices"`
	Usage   ChatCompletionUsage `json:"usage"`
}

CompletionResponse is the text_completion wire response.

type CompletionTokensDetails

type CompletionTokensDetails struct {
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
	AudioTokens     int `json:"audio_tokens,omitempty"`
}

CompletionTokensDetails is the OpenAI breakdown of completion-side token usage.

type ConversationObject added in v0.3.8

type ConversationObject struct {
	ID        string            `json:"id"`
	Object    string            `json:"object"`
	CreatedAt int64             `json:"created_at"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

ConversationObject is the stored and served conversation.

type Credential

type Credential struct {
	ID         string         `json:"id"`
	ProviderID string         `json:"provider_id"`
	Label      string         `json:"label"`
	Data       map[string]any `json:"data"`
	ExpiresAt  *time.Time     `json:"expires_at,omitempty"`
	CreatedAt  time.Time      `json:"created_at"`
	UpdatedAt  time.Time      `json:"updated_at"`

	LastUsedAt   *time.Time `json:"last_used_at,omitempty"`
	RequestCount int64      `json:"request_count"`
	SuccessCount int64      `json:"success_count"`
	FailureCount int64      `json:"failure_count"`

	// Disabled excludes the credential from routing and fallthrough.
	Disabled bool `json:"disabled,omitempty"`
	// DisabledBy names who disabled the credential: DisabledByAdmin.
	// Empty when enabled.
	DisabledBy string `json:"disabled_by,omitempty"`
	// DisabledReason carries the human reason (admin note).
	DisabledReason string `json:"disabled_reason,omitempty"`
	// DisabledAt marks when the credential was disabled. Nil when enabled.
	DisabledAt *time.Time `json:"disabled_at,omitempty"`
	// Order is the admin-defined pool position (1-based). 0 means unordered:
	// unordered credentials sort after ordered ones by computed priority.
	Order int `json:"order,omitempty"`
}

Credential holds provider-specific authentication data. Data is a flexible map to support any auth scheme, including non-string values such as expiry timestamps.

func (*Credential) DataString

func (c *Credential) DataString(key string) string

DataString returns a string view of a data value for Go adapters that only understand string credentials.

func (*Credential) ExpiresIn

func (c *Credential) ExpiresIn() time.Duration

ExpiresIn returns the duration until expiry (negative if already expired).

func (*Credential) IncrementUsage

func (c *Credential) IncrementUsage(success bool)

IncrementUsage updates usage statistics after a request.

func (*Credential) IsExpired

func (c *Credential) IsExpired() bool

IsExpired reports whether the credential has passed its expiry time.

func (*Credential) Priority

func (c *Credential) Priority() int

Priority returns the selection priority for this credential: unused first, then used, expired last. Limit state lives in the exhausted store, never on the credential.

type CredentialScope added in v0.1.2

type CredentialScope struct {
	ProviderID    string   `json:"provider_id"`
	All           bool     `json:"all"`
	CredentialIDs []string `json:"credential_ids,omitempty"`
}

CredentialScope grants a token access to credentials of one provider.

type CustomProxyPool added in v0.3.8

type CustomProxyPool struct {
	ID        string       `json:"id"`
	Name      string       `json:"name"`
	Entries   []ProxyEntry `json:"entries"`
	CreatedAt time.Time    `json:"created_at"`
	UpdatedAt time.Time    `json:"updated_at"`
}

CustomProxyPool is a manually created and populated proxy pool.

type Embedding added in v0.0.5

type Embedding struct {
	Index int `json:"index"`
	// Object is always "embedding" on the wire; Values holds the float
	// vector, B64Values the base64 float32-LE rendering (exactly one is
	// set when marshaled). Custom MarshalJSON/UnmarshalJSON own the wire
	// mapping; these tags serve the spec generator only.
	Object    string    `json:"object,omitempty" example:"embedding"`
	Values    []float64 `json:"embedding,omitempty"`
	B64Values string    `json:"-"`
}

func (Embedding) MarshalJSON added in v0.0.5

func (e Embedding) MarshalJSON() ([]byte, error)

MarshalJSON renders one embedding entry in the OpenAI shape: float array by default, base64 float32-LE when the client asked for base64.

func (*Embedding) UnmarshalJSON added in v0.0.5

func (e *Embedding) UnmarshalJSON(raw []byte) error

UnmarshalJSON accepts the plugin-side embedding entry: the OpenAI {index, embedding:[...]} shape with float values.

type EmbeddingsRequest added in v0.0.5

type EmbeddingsRequest struct {
	Model          ModelId  `json:"model"`
	Input          []string `json:"input,omitempty"`
	EncodingFormat string   `json:"encoding_format,omitempty"` // float (default) or base64
	Dimensions     int      `json:"dimensions,omitempty"`
	// OutputDimension is the Mistral alias for Dimensions.
	OutputDimension int `json:"output_dimension,omitempty"`
	// OutputDtype is accepted and documented; vectors stay float32.
	OutputDtype string `json:"output_dtype,omitempty"`
	// Truncate is accepted; over-long inputs are embedded whole.
	Truncate any `json:"truncate,omitempty"`
}

EmbeddingsRequest is the parsed body of POST /v1/embeddings. Input is normalized to a list of strings at the edge: OpenAI accepts a single string, a list of strings, or token arrays; token arrays are decoded by clients upstream of this router and are refused here.

Alias fields translate derivative clients: OutputDimension (Mistral `output_dimension`), OutputDtype (accepted, plugins always return float vectors), Truncate (accepted, inputs are used whole). NormalizeAliases folds OutputDimension into Dimensions.

func (*EmbeddingsRequest) NormalizeAliases added in v0.3.8

func (r *EmbeddingsRequest) NormalizeAliases()

NormalizeAliases folds the output_dimension alias into Dimensions.

func (*EmbeddingsRequest) UnmarshalJSON added in v0.0.5

func (r *EmbeddingsRequest) UnmarshalJSON(raw []byte) error

embeddingsRequestJSON decodes the polymorphic OpenAI input field.

type EmbeddingsResponse added in v0.0.5

type EmbeddingsResponse struct {
	Data  []Embedding      `json:"data"`
	Model string           `json:"model"`
	Usage *EmbeddingsUsage `json:"usage,omitempty"`
}

EmbeddingsResponse is the normalized plugin return and the client wire response. Plugins always return float vectors; the edge renders encoding_format=base64 from them.

type EmbeddingsUsage added in v0.0.5

type EmbeddingsUsage struct {
	PromptTokens int `json:"prompt_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error" example:"invalid request"`
}

ErrorResponse is the standard error response format for all API endpoints.

type ImageData added in v0.0.5

type ImageData struct {
	URL           string `json:"url,omitempty"`
	B64JSON       string `json:"b64_json,omitempty"`
	RevisedPrompt string `json:"revised_prompt,omitempty"`
}

type ImageGenerationRequest added in v0.0.5

type ImageGenerationRequest struct {
	Model          ModelId `json:"model"`
	Prompt         string  `json:"prompt"`
	N              int     `json:"n,omitempty"`
	Size           string  `json:"size,omitempty"`
	Quality        string  `json:"quality,omitempty"`
	Style          string  `json:"style,omitempty"`
	ResponseFormat string  `json:"response_format,omitempty"` // url or b64_json
	// ImageB64 holds the base64 source image for edits/variations.
	ImageB64 string `json:"image_b64,omitempty"`
	// ImageName carries the uploaded file name for logging only.
	ImageName string `json:"image_name,omitempty"`
	// MaskB64 holds the base64 edit mask (edits only).
	MaskB64 string `json:"mask_b64,omitempty"`
}

ImageGenerationRequest is the parsed body of POST /v1/images/generations and, with edit fields set, of POST /v1/images/edits and POST /v1/images/variations. ImageB64/MaskB64 carry the multipart uploads as base64 (never serialized to clients); plugins that predate them ignore the extra table fields.

type ImageGenerationResponse added in v0.0.5

type ImageGenerationResponse struct {
	Created int64       `json:"created"`
	Data    []ImageData `json:"data"`
}

ImageGenerationResponse is the normalized plugin return and the client wire response: the OpenAI images shape.

type MetricEvent

type MetricEvent struct {
	Timestamp    time.Time
	ProviderID   string
	ProviderType string
	Model        ModelId
	TokenID      string
	Duration     time.Duration
	StatusCode   int
	TokensInput  int64
	TokensOutput int64
	ErrorType    string
}

MetricEvent represents a single API request event.

type MetricsFilters

type MetricsFilters struct {
	ProviderID string    `json:"provider_id"`
	Model      ModelId   `json:"model"`
	TimeRange  TimeRange `json:"time_range"`
}

MetricsFilters for querying metrics.

type MetricsOverview

type MetricsOverview struct {
	TotalRequests    int64 `json:"total_requests" example:"1500"`
	TotalErrors      int64 `json:"total_errors" example:"23"`
	PeakRequests     int64 `json:"peak_requests" example:"45"`
	PeakInputTokens  int64 `json:"peak_input_tokens" example:"12000"`
	PeakOutputTokens int64 `json:"peak_output_tokens" example:"3500"`
}

MetricsOverview for dashboard display.

type ModelArchitecture added in v0.3.8

type ModelArchitecture struct {
	InputModalities  []string `json:"input_modalities,omitempty"`
	OutputModalities []string `json:"output_modalities,omitempty"`
	Modality         string   `json:"modality,omitempty"`
}

ModelArchitecture carries OpenRouter-style modality details on a model card.

type ModelEntry added in v0.3.8

type ModelEntry struct {
	ID                  string             `json:"id"`
	Object              string             `json:"object"`
	Created             int64              `json:"created"`
	OwnedBy             string             `json:"owned_by"`
	Name                string             `json:"name,omitempty"`
	Description         string             `json:"description,omitempty"`
	ContextLength       int64              `json:"context_length,omitempty"`
	MaxCompletionTokens int64              `json:"max_completion_tokens,omitempty"`
	Architecture        *ModelArchitecture `json:"architecture,omitempty"`
	Reasoning           *ModelReasoning    `json:"reasoning,omitempty"`
	SupportedParameters []string           `json:"supported_parameters,omitempty"`
	Capabilities        []string           `json:"capabilities,omitempty"`
}

ModelEntry is one /v1/models card: OpenAI canonical fields plus the OpenRouter-style extension set.

type ModelId

type ModelId string

ModelId uniquely identifies a model in the format: provider/model-name[:version]

func (ModelId) Name added in v0.1.2

func (m ModelId) Name() string

Name returns the model name without the provider prefix: everything after the first '/'. Plugins sending the bare name upstream use this instead of hand-rolled stripping. Invalid ids yield the full id unchanged.

func (ModelId) Parse

func (m ModelId) Parse() (providerID, model string, err error)

Parse splits a ModelId into providerID and model name. Both parts must be non-empty: "/model" and "provider/" are rejected instead of routing with an empty half.

func (ModelId) ParseFull

func (m ModelId) ParseFull() (adapterType, qualifier, model string, err error)

ParseFull splits a ModelId into adapter type, qualifier, and model name.

func (ModelId) ParseStructured added in v0.3.8

func (m ModelId) ParseStructured() (ParsedModelId, error)

ParseStructured parses a ModelId into its structured form.

func (ModelId) String

func (m ModelId) String() string

type ModelInfo

type ModelInfo struct {
	Name          string `json:"name"`
	DisplayName   string `json:"display_name"`
	Description   string `json:"description,omitempty"`
	RPM           int64  `json:"rpm"`
	TPM           int64  `json:"tpm"`
	RPD           int64  `json:"rpd"`
	ContextWindow int64  `json:"context_window,omitempty"`
	MaxTokens     int64  `json:"max_tokens,omitempty"`

	// Capabilities are UI-facing feature chips (tools, json_mode, ...).
	// Derived from the fields below when the plugin does not set them.
	// Modalities stay out: they render in their own column.
	Capabilities []string `json:"capabilities,omitempty"`

	InputModalities     []string        `json:"input_modalities,omitempty"`
	OutputModalities    []string        `json:"output_modalities,omitempty"`
	SupportedParameters []string        `json:"supported_parameters,omitempty"`
	Reasoning           *ModelReasoning `json:"reasoning,omitempty"`

	// Endpoints lists the served endpoint identifiers (Endpoint* constants).
	// Empty means chat/completions only.
	Endpoints []string `json:"endpoints,omitempty"`
}

ModelInfo contains metadata about a specific model. Field style follows the OpenRouter model schema where applicable.

func (*ModelInfo) DeriveCapabilities

func (m *ModelInfo) DeriveCapabilities()

DeriveCapabilities fills Capabilities from the OpenRouter-style fields. Explicit plugin-provided capabilities win.

func (*ModelInfo) SupportsEndpoint added in v0.0.5

func (m *ModelInfo) SupportsEndpoint(endpoint string) bool

SupportsEndpoint reports whether the model serves endpoint. Empty Endpoints implies chat/completions only.

type ModelListResponse added in v0.3.8

type ModelListResponse struct {
	Object string       `json:"object"`
	Data   []ModelEntry `json:"data"`
}

ModelListResponse is the GET /v1/models wire response.

type ModelOverride

type ModelOverride struct {
	ProviderID   string   `json:"provider_id"`
	Name         string   `json:"name"`
	Disabled     bool     `json:"disabled,omitempty"`
	Custom       bool     `json:"custom,omitempty"`
	DisplayName  string   `json:"display_name,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
	// InputModalities and OutputModalities hold probe-verified modalities,
	// keyed by full model id. Applied over upstream data when non-empty.
	InputModalities  []string `json:"input_modalities,omitempty"`
	OutputModalities []string `json:"output_modalities,omitempty"`
}

ModelOverride is the per-provider admin override for a single model: disable from routing and /v1/models, register a custom model the upstream does not list, or adjust display metadata.

type ModelReasoning

type ModelReasoning struct {
	// SupportedEfforts in descending effort order (highest first).
	SupportedEfforts []string `json:"supported_efforts,omitempty"`
	DefaultEffort    string   `json:"default_effort,omitempty"`
	DefaultEnabled   bool     `json:"default_enabled,omitempty"`
	Mandatory        bool     `json:"mandatory,omitempty"`
}

ModelReasoning describes reasoning support of a model (OpenRouter-style).

type ModerationRequest added in v0.3.8

type ModerationRequest struct {
	Model ModelId  `json:"model"`
	Input []string `json:"-"`
}

ModerationRequest is the incoming POST /v1/moderations body. Input is normalized at the edge: a string, a list of strings, or a list of message-like parts (Mistral chat/moderations shape) joined to text.

func (*ModerationRequest) UnmarshalJSON added in v0.3.8

func (r *ModerationRequest) UnmarshalJSON(raw []byte) error

UnmarshalJSON accepts input as string, string array, or parts array with text fields.

type ModerationResponse added in v0.3.8

type ModerationResponse struct {
	ID      string             `json:"id"`
	Model   string             `json:"model"`
	Results []ModerationResult `json:"results"`
}

ModerationResponse is the moderation wire response.

type ModerationResult added in v0.3.8

type ModerationResult struct {
	Flagged        bool               `json:"flagged"`
	Categories     map[string]bool    `json:"categories"`
	CategoryScores map[string]float64 `json:"category_scores"`
}

ModerationResult is one per-input verdict.

type OpenAIError

type OpenAIError struct {
	Error OpenAIErrorBody `json:"error"`
}

OpenAIError wraps error responses in the OpenAI error format.

type OpenAIErrorBody

type OpenAIErrorBody struct {
	Message string  `json:"message" example:"Invalid request: missing required field 'model'"`
	Type    string  `json:"type" example:"invalid_request_error"`
	Param   *string `json:"param" example:"model"`
	Code    string  `json:"code,omitempty" example:"invalid_request"`
}

type ParkEntry added in v0.3.8

type ParkEntry struct {
	CredentialID string    `json:"credential_id"`
	Reason       string    `json:"reason,omitempty"`
	Until        time.Time `json:"until"`
	ParkedAt     time.Time `json:"parked_at"`
}

ParkEntry is one unified cooldown park: the credential stays enabled and dashboard-visible, but plugin rotation skips it until Until passes. Transient states only (rate limits, quota windows); dead keys disable.

func (*ParkEntry) Expired added in v0.3.8

func (e *ParkEntry) Expired(now time.Time) bool

Expired reports whether the park no longer holds.

type ParsedModelId added in v0.3.8

type ParsedModelId struct {
	ProviderID  string
	AdapterType string
	Qualifier   string
	Model       string
}

ParsedModelId groups ModelId parse outputs. New code prefers this over the multi-return Parse/ParseFull pair; existing callers stay untouched.

type PluginInternalError

type PluginInternalError struct {
	PluginID string
	TypeKey  string
	Cause    string
}

PluginInternalError is a caught Lua failure at the Go/Lua boundary.

func (*PluginInternalError) Error

func (e *PluginInternalError) Error() string

type PromptTokensDetails

type PromptTokensDetails struct {
	CachedTokens int `json:"cached_tokens,omitempty"`
	AudioTokens  int `json:"audio_tokens,omitempty"`
}

PromptTokensDetails is the OpenAI breakdown of prompt-side token usage.

type ProviderError

type ProviderError struct {
	StatusCode int
	Message    string
	Code       string
	Param      string
	Headers    map[string]string `json:"-"`
}

ProviderError is the terminal error a plugin returns when its own retries are exhausted. The shape mirrors the OpenAI error object: a human message plus a wire code. Routing never inspects anything else, except the optional response Headers map, which the HTTP layer renders through its allow-list (Retry-After today). Headers never reach JSON envelopes or stored records.

func (*ProviderError) Error

func (e *ProviderError) Error() string

type ProviderInstance

type ProviderInstance struct {
	ID           string         `json:"id" example:"opencode-zen"`
	Name         string         `json:"name" example:"OpenCode Zen"`
	TypeKey      string         `json:"type_key" example:"opencode-zen"`
	Qualifier    string         `json:"qualifier" example:""`
	Config       map[string]any `json:"config"`
	IconURL      string         `json:"icon_url" example:"https://cdn.example.com/openai.svg"`
	IsUIReadonly bool           `json:"is_ui_readonly"`
	IsUIHidden   bool           `json:"is_ui_hidden"`
	// Disabled takes the provider out of routing and model listings.
	// Settings and discovery keep working.
	Disabled bool `json:"disabled,omitempty"`
	// DisabledBy names who disabled the provider: DisabledByAdmin
	// (dashboard PUT) or DisabledBySystem (doctor fix for backend-less
	// types). Empty when enabled.
	DisabledBy string `json:"disabled_by,omitempty"`
	// DisabledReason carries the human reason (system cause or admin note).
	DisabledReason string `json:"disabled_reason,omitempty"`
	// DisabledAt marks when the provider was disabled. Nil when enabled.
	DisabledAt *time.Time `json:"disabled_at,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
}

ProviderInstance is the single persisted provider record for every type: lua-plugin type keys, built-in "custom" and "virtual".

func (*ProviderInstance) BaseURL

func (p *ProviderInstance) BaseURL() string

BaseURL returns Config["base_url"] for OpenAI-compatible providers.

type ProviderInstanceCreateRequest

type ProviderInstanceCreateRequest struct {
	Name      string         `json:"name"`
	TypeKey   string         `json:"type_key"`
	Qualifier string         `json:"qualifier"`
	Config    map[string]any `json:"config"`
	IconURL   string         `json:"icon_url"`
}

ProviderInstanceCreateRequest is the create body for custom providers. TypeKey must be "custom"; Qualifier is ignored by the dashboard handler and kept only for backward compatibility with older clients.

type ProviderInstanceUpdateRequest

type ProviderInstanceUpdateRequest struct {
	Name     string         `json:"name"`
	Config   map[string]any `json:"config"`
	IconURL  string         `json:"icon_url"`
	Disabled *bool          `json:"disabled"`
}

ProviderInstanceUpdateRequest is the generic update body.

type ProviderStats

type ProviderStats struct {
	ModelCount      int `json:"model_count" example:"5"`
	CredentialCount int `json:"credential_count" example:"2"`
}

ProviderStats holds aggregated statistics for a provider.

type ProxyDataBundle added in v0.4.2

type ProxyDataBundle struct {
	Version  int               `json:"version"`
	Settings *ProxyDataSetting `json:"settings,omitempty"`
	Pools    []CustomProxyPool `json:"pools"`
	Proxies  []ProxyDataEntry  `json:"proxies"`
}

ProxyDataBundle packages the proxy subsystem for export and import: switches and cap, manually managed pools and the currently healthy discovered proxies. Banned and unchecked proxies are volatile and stay out.

type ProxyDataEntry added in v0.4.2

type ProxyDataEntry struct {
	URL     string `json:"url"`
	Country string `json:"country,omitempty"`
}

ProxyDataEntry is one discovered proxy. Import queues it for a fresh check.

type ProxyDataSetting added in v0.4.2

type ProxyDataSetting struct {
	Enabled     bool `json:"enabled"`
	PoolEnabled bool `json:"pool_enabled"`
	MaxChecks   int  `json:"max_checks"`
}

ProxyDataSetting carries the proxy switches and the check cap.

type ProxyEntry added in v0.3.8

type ProxyEntry struct {
	URL     string `json:"url"`
	Country string `json:"country,omitempty"`
}

ProxyEntry is one proxy endpoint in a custom pool.

type ProxyPoolRef added in v0.3.8

type ProxyPoolRef struct {
	Pool string `json:"pool,omitempty"`
}

ProxyPoolRef is the provider-level proxy selection stored in ProviderInstance.Config["proxy"]. Empty pool means direct (no proxy): plugins skip proxies.query. "auto" selects the router free pool, any other name selects a custom pool by ID or name.

func ParseProxyPoolRef added in v0.3.8

func ParseProxyPoolRef(providerConfig map[string]any) (ProxyPoolRef, error)

ParseProxyPoolRef reads the provider-level proxy pool reference from a provider config map. Absent or non-map proxy sections mean direct; an explicitly unknown shape is an error, never a silent fallback.

type ProxyRequire added in v0.3.8

type ProxyRequire struct {
	// Pool is "" (direct), "auto" (free pool) or a custom pool ID/name.
	Pool string
	// Countries is an OR list of ISO codes; empty accepts any country.
	Countries []string
	// Exclude lists proxy URLs that must not be returned.
	Exclude []string
	// Limit is the maximum number of proxies returned (at least 1).
	Limit int
	// Want is the free-pool country stock to maintain; zero uses the pool default.
	Want int
	// Timeout bounds the wait on the free pool.
	Timeout time.Duration
}

ProxyRequire is one proxies.require call.

type ProxyRequireResult added in v0.3.8

type ProxyRequireResult struct {
	Proxies  []ProxyView
	TimedOut bool
	// Direct reports that the provider is configured without a proxy pool.
	Direct bool
	// Disabled reports that a pool was requested but the router-wide proxy
	// switches are off. The plugin fallback decides: fail, or go direct.
	Disabled bool
}

ProxyRequireResult is the outcome of proxies.require. Proxies is empty for a direct pool, a disabled pool, a timeout, or a custom pool without a matching entry.

type ProxyView added in v0.3.8

type ProxyView struct {
	ID      string `json:"id"`
	URL     string `json:"url"`
	Country string `json:"country,omitempty"`
	Pool    string `json:"pool"`
}

ProxyView is one proxy endpoint exposed to plugins through proxies.query.

type ReasoningConfig added in v0.3.8

type ReasoningConfig struct {
	Effort    string `json:"effort,omitempty"`
	MaxTokens *int   `json:"max_tokens,omitempty"`
	Exclude   *bool  `json:"exclude,omitempty"`
	Enabled   *bool  `json:"enabled,omitempty"`
}

ReasoningConfig is the OpenRouter `reasoning` envelope: effort maps to ReasoningEffort, MaxTokens caps reasoning output.

type RecheckBannedRequest added in v0.3.8

type RecheckBannedRequest struct {
	Reason string `json:"reason"`
	Source string `json:"source"`
}

RecheckBannedRequest selects banned proxies for manual rechecking. Both filters are optional.

type RecheckBannedResponse added in v0.3.8

type RecheckBannedResponse struct {
	Queued int `json:"queued"`
}

RecheckBannedResponse reports the number of queued manual rechecks.

type ResponseContentPart added in v0.4.0

type ResponseContentPart struct {
	Type        string `json:"type"`
	Text        string `json:"text"`
	Annotations []any  `json:"annotations"`
}

ResponseContentPart is one typed block of a message item.

type ResponseError added in v0.3.8

type ResponseError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ResponseError carries a failed response cause.

type ResponseInputItem added in v0.3.8

type ResponseInputItem struct {
	Type      string          `json:"type,omitempty"`
	ID        string          `json:"id,omitempty"`
	Role      string          `json:"role,omitempty"`
	Content   json.RawMessage `json:"content,omitempty"`
	Name      string          `json:"name,omitempty"`
	CallID    string          `json:"call_id,omitempty"`
	Arguments string          `json:"arguments,omitempty"`
	Output    json.RawMessage `json:"output,omitempty"`
}

ResponseInputItem is one input item: message, function call, function call output or reasoning. Content and Output stay opaque JSON until ResponseRequest.ToChat decodes them per item type.

type ResponseObject added in v0.3.8

type ResponseObject struct {
	ID                 string               `json:"id"`
	Object             string               `json:"object"`
	CreatedAt          int64                `json:"created_at"`
	Model              string               `json:"model"`
	Status             string               `json:"status"`
	Output             []ResponseOutputItem `json:"output"`
	Usage              *ResponseUsage       `json:"usage,omitempty"`
	Instructions       string               `json:"instructions,omitempty"`
	PreviousResponseID string               `json:"previous_response_id,omitempty"`
	ConversationID     string               `json:"conversation,omitempty"`
	Metadata           map[string]string    `json:"metadata,omitempty"`
	Error              *ResponseError       `json:"error,omitempty"`
}

ResponseObject is the stored and served response.

func ResponseObjectFromChat added in v0.4.0

func ResponseObjectFromChat(id string, request *ResponseRequest, response *ChatCompletionResponse) *ResponseObject

ResponseObjectFromChat maps one chat completion onto a completed response object. Assistant text becomes a message item. Each tool call becomes a function_call item whose call_id is the identifier the client echoes back in its function_call_output item.

type ResponseOutputItem added in v0.3.8

type ResponseOutputItem struct {
	Type      string                `json:"type"`
	ID        string                `json:"id,omitempty"`
	Status    string                `json:"status,omitempty"`
	Role      string                `json:"role,omitempty"`
	Text      string                `json:"text,omitempty"`
	Content   []ResponseContentPart `json:"content,omitempty"`
	Name      string                `json:"name,omitempty"`
	CallID    string                `json:"call_id,omitempty"`
	Arguments string                `json:"arguments,omitempty"`
}

ResponseOutputItem is one produced output block. Messages carry Content (output_text parts) and Text for clients that read the flat form. Function calls carry CallID and Arguments; function_call_output items echo CallID back.

type ResponseRecord added in v0.3.8

type ResponseRecord struct {
	ID        string             `json:"id"`
	Kind      ResponseRecordKind `json:"kind"`
	Model     ModelId            `json:"model"`
	Status    string             `json:"status,omitempty"`
	ParentID  string             `json:"parent_id,omitempty"`
	RefID     string             `json:"ref_id,omitempty"`
	Payload   json.RawMessage    `json:"payload,omitempty"`
	Input     json.RawMessage    `json:"input,omitempty"`
	CreatedAt time.Time          `json:"created_at"`
	UpdatedAt time.Time          `json:"updated_at"`
}

ResponseRecord is one row in the responses bucket: every async compat object (response, conversation, assistant, thread, message, run) shares this envelope. Payload holds the wire object JSON; ParentID links thread children and run bindings (thread id); RefID links runs to assistants and responses to previous responses. Input holds the opaque input that produced the object (response input items, conversation items, pending run chat turns) for input_items listings and tool-output continuations.

type ResponseRecordKind added in v0.3.8

type ResponseRecordKind string

ResponseRecordKind discriminates rows in the responses bucket.

const (
	ResponseRecordResponse      ResponseRecordKind = "response"
	ResponseRecordConversation  ResponseRecordKind = "conversation"
	ResponseRecordAssistant     ResponseRecordKind = "assistant"
	ResponseRecordThread        ResponseRecordKind = "thread"
	ResponseRecordThreadMessage ResponseRecordKind = "thread_message"
	ResponseRecordRun           ResponseRecordKind = "run"
)

type ResponseRequest added in v0.3.8

type ResponseRequest struct {
	Model              ModelId           `json:"model"`
	Input              json.RawMessage   `json:"input,omitempty"`
	Instructions       string            `json:"instructions,omitempty"`
	Tools              []json.RawMessage `json:"tools,omitempty"`
	ToolChoice         any               `json:"tool_choice,omitempty"`
	Reasoning          *ReasoningConfig  `json:"reasoning,omitempty"`
	ReasoningEffort    *string           `json:"reasoning_effort,omitempty"`
	Text               json.RawMessage   `json:"text,omitempty"`
	Stream             bool              `json:"stream,omitempty"`
	MaxOutputTokens    *int              `json:"max_output_tokens,omitempty"`
	Store              *bool             `json:"store,omitempty"`
	Background         *bool             `json:"background,omitempty"`
	PreviousResponseID string            `json:"previous_response_id,omitempty"`
	ConversationID     string            `json:"conversation,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"`
	User               *string           `json:"user,omitempty"`
}

ResponseRequest is the incoming POST /v1/responses body. Input accepts a plain string or response input items; tools accept web_search, file_search, function and mcp definitions (stored, function tools execute through the chat pipeline).

func (*ResponseRequest) InputTexts added in v0.3.8

func (r *ResponseRequest) InputTexts() []string

InputTexts renders the request input as chat text turns.

func (*ResponseRequest) ToChat added in v0.3.8

ToChat maps the response request onto the chat pipeline: instructions become the system turn, input items become chat turns, function tools become chat tools.

type ResponseStreamEvent added in v0.4.0

type ResponseStreamEvent struct {
	Name string
	Data map[string]any
}

ResponseStreamEvent is one server-sent event of a Responses stream: the SSE event name and the JSON payload. The payload's type field repeats the name.

func ResponseStreamEvents added in v0.4.0

func ResponseStreamEvents(response *ResponseObject) []ResponseStreamEvent

ResponseStreamEvents expands a completed response into the event sequence a Responses client consumes: response.created, the added, delta and done events of each output item in order, then response.completed. Every payload carries its type field, and the item indexes the client matches on.

type ResponseUsage added in v0.3.8

type ResponseUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

ResponseUsage mirrors chat usage for response objects.

type RouterConfiguration

type RouterConfiguration struct {
	IsClusterNode    bool `json:"is_cluster_node"`
	DisableTelemetry bool `json:"disable_telemetry"`
	// ModelsFilter remembers the dashboard model visibility filter
	// ("all", "enabled", "disabled"). Empty means "all".
	ModelsFilter string `json:"models_filter,omitempty"`
	// ProxyMaxChecks caps parallel proxy checks. Zero keeps the adaptive
	// default. A nil value on write keeps the stored setting.
	ProxyMaxChecks *int `json:"proxy_max_checks,omitempty"`
	// ProxyEnabled switches the whole proxy subsystem. Off keeps all data but
	// stops discovery and sends every provider request direct. A nil value on
	// write keeps the stored setting; the default is on.
	ProxyEnabled *bool `json:"proxy_enabled,omitempty"`
	// ProxyPoolEnabled switches the automatic free pool alone. Off keeps only
	// the manually managed pools. A nil value on write keeps the stored
	// setting; the default is on.
	ProxyPoolEnabled *bool `json:"proxy_pool_enabled,omitempty"`
}

RouterConfiguration holds deployment-wide instance settings.

func (RouterConfiguration) Validate

func (c RouterConfiguration) Validate() error

Validate checks the configuration ranges.

type RouterToken

type RouterToken struct {
	ID        string     `json:"id" example:"token123"`
	Name      string     `json:"name" example:"Production API Token"`
	Token     string     `json:"token,omitempty" example:"llmr_abc123def456"`
	TokenHash string     `json:"token_hash,omitempty"`
	Rules     TokenRules `json:"rules"`
	CreatedAt time.Time  `json:"created_at" example:"2026-05-04T15:00:00Z"`
}

RouterToken is an opaque bearer token issued by llm-router itself.

type Run added in v0.3.8

type Run struct {
	ID             string             `json:"id"`
	Object         string             `json:"object"`
	CreatedAt      int64              `json:"created_at"`
	ThreadID       string             `json:"thread_id"`
	AssistantID    string             `json:"assistant_id"`
	Model          string             `json:"model"`
	Status         string             `json:"status"`
	Instructions   string             `json:"instructions,omitempty"`
	RequiredAction *RunRequiredAction `json:"required_action,omitempty"`
	Metadata       map[string]string  `json:"metadata,omitempty"`
}

Run is one assistant execution inside a thread, mapped onto a resp_* response execution.

type RunRequest added in v0.3.8

type RunRequest struct {
	AssistantID  string            `json:"assistant_id"`
	Model        ModelId           `json:"model,omitempty"`
	Instructions string            `json:"instructions,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	Stream       bool              `json:"stream,omitempty"`
}

RunRequest is the create body for runs.

type RunRequiredAction added in v0.3.8

type RunRequiredAction struct {
	Type              string             `json:"type"`
	SubmitToolOutputs *SubmitToolOutputs `json:"submit_tool_outputs,omitempty"`
}

RunRequiredAction carries tool outputs the client must submit.

type RunToolCall added in v0.3.8

type RunToolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

RunToolCall is one function call awaiting a client output.

type SpeechRequest added in v0.0.5

type SpeechRequest struct {
	Model          ModelId  `json:"model"`
	Input          string   `json:"input"`
	Voice          string   `json:"voice"`
	ResponseFormat string   `json:"response_format,omitempty"` // mp3 (default), opus, aac, flac, wav, pcm
	Speed          *float64 `json:"speed,omitempty"`
	Instructions   string   `json:"instructions,omitempty"`
}

SpeechRequest is the parsed body of POST /v1/audio/speech.

type SpeechResponse added in v0.0.5

type SpeechResponse struct {
	Audio  []byte
	Format string // mp3, opus, aac, flac, wav, pcm
}

SpeechResponse is the normalized plugin return: raw audio bytes plus the format they are encoded in. The router serves the bytes with the matching Content-Type; no transcoding happens inside the router.

type StreamChunk

type StreamChunk struct {
	ID      string               `json:"id"`
	Object  string               `json:"object"`
	Created int64                `json:"created"`
	Model   string               `json:"model"`
	Choices []StreamChunkChoice  `json:"choices"`
	Usage   *ChatCompletionUsage `json:"usage,omitempty"`
}

StreamChunk is a single SSE data payload for streaming responses.

type StreamChunkChoice

type StreamChunkChoice struct {
	Index        int         `json:"index"`
	Delta        ChatMessage `json:"delta"`
	FinishReason *string     `json:"finish_reason"`
	Logprobs     any         `json:"logprobs,omitempty"`
}

type StreamOptions

type StreamOptions struct {
	IncludeUsage bool `json:"include_usage,omitempty"`
}

StreamOptions for streaming

type SubmitToolOutputs added in v0.3.8

type SubmitToolOutputs struct {
	ToolCalls []RunToolCall `json:"tool_calls"`
}

SubmitToolOutputs lists tool calls awaiting outputs.

type Thread added in v0.3.8

type Thread struct {
	ID        string            `json:"id"`
	Object    string            `json:"object"`
	CreatedAt int64             `json:"created_at"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

Thread is a conversation handle in the prior-generation API.

type ThreadContent added in v0.3.8

type ThreadContent struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

ThreadContent is one text block of a thread message.

type ThreadMessage added in v0.3.8

type ThreadMessage struct {
	ID        string            `json:"id"`
	Object    string            `json:"object"`
	CreatedAt int64             `json:"created_at"`
	ThreadID  string            `json:"thread_id"`
	Role      string            `json:"role"`
	Content   []ThreadContent   `json:"content"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

ThreadMessage is one message inside a thread.

type ThreadMessageRequest added in v0.3.8

type ThreadMessageRequest struct {
	Role     string            `json:"role"`
	Content  json.RawMessage   `json:"content"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

ThreadMessageRequest is the create body for thread messages.

func (*ThreadMessageRequest) ThreadMessageTexts added in v0.3.8

func (r *ThreadMessageRequest) ThreadMessageTexts() []string

ThreadMessageTexts renders the request content as plain texts.

type TimeRange

type TimeRange string

TimeRange represents a time window for metrics queries.

const (
	TimeRangeHour      TimeRange = "hour"
	TimeRange1Day      TimeRange = "1d"
	TimeRange7Days     TimeRange = "7d"
	TimeRange28Days    TimeRange = "28d"
	TimeRange90Days    TimeRange = "90d"
	TimeRangeThisMonth TimeRange = "month"
)

func (TimeRange) Bounds

func (tr TimeRange) Bounds() (start, end time.Time)

Bounds returns the start and end times for this time range.

type TimeSeriesPoint

type TimeSeriesPoint struct {
	Timestamp time.Time `json:"timestamp" example:"2026-05-04T19:00:00Z"`
	Value     int64     `json:"value" example:"42"`
}

TimeSeriesPoint for chart data.

type TokenRules

type TokenRules struct {
	AllowedProviders    []string  `json:"allowed_providers"`
	AllowAllProviders   bool      `json:"allow_all_providers"`
	AllowedModels       []ModelId `json:"allowed_models"`
	AllowAllModels      bool      `json:"allow_all_models"`
	AllowedCredentials  []string  `json:"allowed_credentials"`
	AllowAllCredentials bool      `json:"allow_all_credentials"`
	// CredentialScopes grants credential access per provider: All covers
	// every current and future key of the provider, CredentialIDs pins
	// specific keys. Scopes union with the legacy flat credential fields.
	CredentialScopes []CredentialScope `json:"credential_scopes,omitempty"`
}

TokenRules constrains what an API token is allowed to do.

func (TokenRules) Allows

func (r TokenRules) Allows(model ModelId) bool

Allows reports whether the token may request the given model.

func (TokenRules) AllowsCredential

func (r TokenRules) AllowsCredential(providerID, credentialID string) bool

AllowsCredential reports whether the token may use the given credential of the given provider. Scopes union with the legacy flat fields: either source granting access allows the credential.

func (TokenRules) AllowsProvider

func (r TokenRules) AllowsProvider(providerID string) bool

AllowsProvider reports whether the token may use the given provider.

type ToolOutput added in v0.3.8

type ToolOutput struct {
	ToolCallID string `json:"tool_call_id"`
	Output     string `json:"output"`
}

ToolOutput is one submitted tool result.

type TranscriptionRequest added in v0.0.5

type TranscriptionRequest struct {
	Task                   string // transcribe or translate
	Model                  ModelId
	File                   []byte
	FileName               string
	ContentType            string
	Language               string
	Prompt                 string
	ResponseFormat         string // json (default), text, srt, verbose_json, vtt
	Temperature            *float64
	TimestampGranularities []string // word, segment
}

TranscriptionRequest is the parsed multipart body of the transcription or translation endpoint. File holds the raw audio bytes.

type TranscriptionResponse added in v0.0.5

type TranscriptionResponse struct {
	Text     string                 `json:"text"`
	Language string                 `json:"language,omitempty"`
	Duration float64                `json:"duration,omitempty"`
	Segments []TranscriptionSegment `json:"segments,omitempty"`
	Words    []TranscriptionWord    `json:"words,omitempty"`
	Task     *string                `json:"task,omitempty"`
}

TranscriptionResponse is the normalized plugin return: the OpenAI verbose_json shape. The router renders the client-facing response_format from these fields. Task echoes the requested task (transcribe/translate) when the edge set one.

func (*TranscriptionResponse) SRT added in v0.0.5

func (r *TranscriptionResponse) SRT() string

SRT renders segments as a SubRip subtitle document.

func (*TranscriptionResponse) VTT added in v0.0.5

func (r *TranscriptionResponse) VTT() string

VTT renders segments as a WebVTT subtitle document.

type TranscriptionSegment added in v0.0.5

type TranscriptionSegment struct {
	ID               int     `json:"id"`
	Seek             int     `json:"seek,omitempty"`
	Start            float64 `json:"start"`
	End              float64 `json:"end"`
	Text             string  `json:"text"`
	Tokens           []int   `json:"tokens,omitempty"`
	Temperature      float64 `json:"temperature,omitempty"`
	AvgLogprob       float64 `json:"avg_logprob,omitempty"`
	CompressionRatio float64 `json:"compression_ratio,omitempty"`
	NoSpeechProb     float64 `json:"no_speech_prob,omitempty"`
}

type TranscriptionWord added in v0.0.5

type TranscriptionWord struct {
	Word  string  `json:"word"`
	Start float64 `json:"start"`
	End   float64 `json:"end"`
}

type UINode

type UINode struct {
	Type         string            `json:"type"`
	Text         string            `json:"text,omitempty"`
	Name         string            `json:"name,omitempty"`
	Label        string            `json:"label,omitempty"`
	InputType    string            `json:"input_type,omitempty"`
	Required     bool              `json:"required,omitempty"`
	Options      []string          `json:"options,omitempty"`
	OptionLabels map[string]string `json:"option_labels,omitempty"`
	URL          string            `json:"url,omitempty"`
	Variant      string            `json:"variant,omitempty"`
	FormAction   string            `json:"form_action,omitempty"`
	Content      []*UINode         `json:"content,omitempty"`
	Placeholder  string            `json:"placeholder,omitempty"`
	Value        any               `json:"value,omitempty"`
	Direction    string            `json:"direction,omitempty"`
	Align        string            `json:"align,omitempty"`
	Justify      string            `json:"justify,omitempty"`
	Gap          int               `json:"gap,omitempty"`
	Columns      int               `json:"columns,omitempty"`
	Title        string            `json:"title,omitempty"`
	Subtitle     string            `json:"subtitle,omitempty"`
	Wrap         bool              `json:"wrap,omitempty"`
	Grow         bool              `json:"grow,omitempty"`
	Size         int               `json:"size,omitempty"`
	Extra        map[string]any    `json:"-"`
}

UINode is a single node of the lua-driven UI tree shared by config_schema, credential_schema and auth wizards.

type VideoContentResponse added in v0.3.8

type VideoContentResponse struct {
	Video       []byte
	ContentType string
}

VideoContentResponse is the normalized plugin return for one video content fetch: raw video bytes plus their media type. The router serves the bytes with the matching Content-Type; no transcoding happens inside the router.

type VideoFrameImage added in v0.3.8

type VideoFrameImage struct {
	Type      string             `json:"type,omitempty"`
	ImageURL  *VideoReferenceURL `json:"image_url,omitempty"`
	FrameType string             `json:"frame_type,omitempty"`
}

VideoFrameImage pins one image as the first or last frame of the generated video. FrameType is `first_frame` or `last_frame`.

type VideoGenerationRequest added in v0.3.8

type VideoGenerationRequest struct {
	Model           ModelId               `json:"model"`
	Prompt          string                `json:"prompt,omitempty"`
	Duration        int                   `json:"duration,omitempty"`
	Resolution      string                `json:"resolution,omitempty"`
	AspectRatio     string                `json:"aspect_ratio,omitempty"`
	Size            string                `json:"size,omitempty"`
	Seed            *int64                `json:"seed,omitempty"`
	GenerateAudio   *bool                 `json:"generate_audio,omitempty"`
	FrameImages     []VideoFrameImage     `json:"frame_images,omitempty"`
	InputReferences []VideoInputReference `json:"input_references,omitempty"`
	PreviousJobID   string                `json:"previous_job_id,omitempty"`
	CallbackURL     string                `json:"callback_url,omitempty"`
	ProviderOptions map[string]any        `json:"provider,omitempty"`
	User            string                `json:"user,omitempty"`
	SessionID       string                `json:"session_id,omitempty"`
}

VideoGenerationRequest is the parsed body of POST /v1/videos.

type VideoGenerationResponse added in v0.3.8

type VideoGenerationResponse struct {
	ID           string                `json:"id"`
	PollingURL   string                `json:"polling_url"`
	Status       string                `json:"status"`
	GenerationID string                `json:"generation_id,omitempty"`
	UnsignedURLs []string              `json:"unsigned_urls,omitempty"`
	Usage        *VideoGenerationUsage `json:"usage,omitempty"`
	Error        string                `json:"error,omitempty"`
}

VideoGenerationResponse is the submit/poll wire shape: the OpenRouter video generation response. On submit the router returns 202 with the router-local ID and polling URL; on poll the same shape carries the terminal state, unsigned download URLs and usage.

type VideoGenerationUsage added in v0.3.8

type VideoGenerationUsage struct {
	Cost   *float64 `json:"cost,omitempty"`
	IsBYOK bool     `json:"is_byok,omitempty"`
}

VideoGenerationUsage carries cost metadata of a completed video job.

type VideoInputReference added in v0.3.8

type VideoInputReference struct {
	Type     string             `json:"type,omitempty"`
	ImageURL *VideoReferenceURL `json:"image_url,omitempty"`
	AudioURL *VideoReferenceURL `json:"audio_url,omitempty"`
	VideoURL *VideoReferenceURL `json:"video_url,omitempty"`
}

VideoInputReference is one reference asset guiding video generation. Exactly one of ImageURL, AudioURL, VideoURL is set; Type names it (`image_url`, `audio_url`, `video_url`).

type VideoJob added in v0.3.8

type VideoJob struct {
	ID            string    `json:"id"`
	Model         ModelId   `json:"model"`
	BackendModel  ModelId   `json:"backend_model"`
	ProviderID    string    `json:"provider_id"`
	TypeKey       string    `json:"type_key"`
	UpstreamJobID string    `json:"upstream_job_id"`
	Status        string    `json:"status"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

VideoJob persists one router-side video generation job: the local ID handed to the client plus the upstream job it polls. Model is the original request model (token authorization on every poll); BackendModel is the model polled upstream (differs for virtual fan-out winners).

type VideoModel added in v0.3.8

type VideoModel struct {
	ID                           string             `json:"id"`
	CanonicalSlug                string             `json:"canonical_slug"`
	Name                         string             `json:"name"`
	Created                      int64              `json:"created"`
	Description                  string             `json:"description,omitempty"`
	SupportedResolutions         []string           `json:"supported_resolutions"`
	SupportedAspectRatios        []string           `json:"supported_aspect_ratios"`
	SupportedSizes               []string           `json:"supported_sizes"`
	SupportedDurations           []int              `json:"supported_durations"`
	SupportedFrameImages         []string           `json:"supported_frame_images"`
	UpscaleFactor                *VideoUpscaleRange `json:"upscale_factor"`
	Creativity                   []int              `json:"creativity"`
	GenerateAudio                *bool              `json:"generate_audio"`
	Seed                         *bool              `json:"seed"`
	AllowedPassthroughParameters []string           `json:"allowed_passthrough_parameters"`
}

VideoModel describes one entry of GET /v1/videos/models: the OpenRouter video model card. Capability fields stay nil when the backend does not report them.

type VideoModelsListResponse added in v0.3.8

type VideoModelsListResponse struct {
	Data []VideoModel `json:"data"`
}

VideoModelsListResponse is the wire shape of GET /v1/videos/models.

type VideoReferenceURL added in v0.3.8

type VideoReferenceURL struct {
	URL string `json:"url,omitempty"`
}

VideoReferenceURL is the `{url}` object of one video reference asset.

type VideoUpscaleRange added in v0.3.8

type VideoUpscaleRange struct {
	Min *float64 `json:"min,omitempty"`
	Max *float64 `json:"max,omitempty"`
}

VideoUpscaleRange bounds the supported upscale factor of a video upscaling model.

type VirtualModel added in v0.0.5

type VirtualModel struct {
	ID          string              `json:"id"`
	Name        string              `json:"name"`
	Description string              `json:"description"`
	Models      []VirtualModelEntry `json:"models"`
	// Instruction is prepended to requests as the first user message.
	Instruction string `json:"instruction"`
	// ManagedBy marks provider-maintained virtual models
	// ("provider:<provider-id>:<endpoint-slug>"). Managed models resolve
	// their member list live from the provider list on every call; stored
	// members are ignored. Empty means manually maintained.
	ManagedBy string `json:"managed_by,omitempty"`
	// Disabled takes the virtual model out of routing. Probes still run.
	Disabled  bool      `json:"disabled,omitempty"`
	Version   int       `json:"version"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

VirtualModel routes requests to its models in list order (fall-through) and reports an error only when every model failed.

type VirtualModelEntry added in v0.0.5

type VirtualModelEntry struct {
	ModelID ModelId `json:"model_id"`
}

VirtualModelEntry is one fall-through step. List order is the priority.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL