Task Plugin API

Mirava supports third-party vendor task APIs (video generation, image generation, etc.) through JavaScript task plugins. A plugin is a single JS file that declares its capabilities in a meta manifest.

Two Entry Surfaces

Surface	Declared by	Description
Plugin-owned routes	`meta.routes`	Register the plugin's own native URLs, shown as "Plugin-defined interfaces"
Host protocols	`meta.protocols`	Claim an existing host protocol without registering or copying its URLs

Manifest Example

export const meta = {
  apiVersion: 1,
  key: 'vendor',
  name: 'Vendor',
  version: '1.0.0',
  author: { name: 'Author' },
  description: { en: 'Video generation via the vendor API', zh: '通过厂商接口生成视频' },
  models: ['vendor-model'],
  fetchMode: 'per_task',
  routes: [
    { method: 'POST', path: '/vendor/v1/jobs', type: 'submit', decode: 'createJob', render: 'jobCreated' },
    { method: 'GET', path: '/vendor/v1/jobs/:task_id', type: 'query', render: 'jobStatus' },
  ],
  protocols: [
    { name: 'openai_responses', supports: ['stream', 'sync', 'background'] },
    'openai_video',
  ],
};

Route Types

type	Required	Description
`submit`	`decode` + `render`	Submit a task
`dynamic`	`decode` + `render`	Dynamic submission
`query`	`render` (no `decode`)	Query a task; default task ID param is `task_id`

Key Fields

Field	Type	Description
`key`	string	Required, unique plugin id, ≤ 30 chars
`name`	string	Required, display name
`version`	string	Required semver
`models`	string[]	Supported models
`icon`	string	Optional LobeHub icon name, or `text` / `text:<label>` for a generated text avatar
`baseUrl`	string	Optional default upstream for type-61 Task Plugin channels
`allowedHosts`	string[]	Optional extra hosts plugin requests may target
`upstreams`	`("vendor"\|"new_api")[]`	Optional upstream kinds the driver addresses
`supports`	string[]	Request forms accepted on `openai_responses`

Protocol Modes

openai_responses accepts three request forms:

Form	Trigger	Description
`stream`	`stream: true`	Streaming
`sync`	No flag	Blocks until terminal
`background`	`background: true`	Returns a pending response immediately

Retrieval (GET /v1/responses/:response_id) is not a mode; every created response is always retrievable.

Icons and Assets

A plugin without a LobeHub icon may ship icon.svg or icon.png beside plugin.js.
Limit: 512 KiB; PNG must carry the PNG signature; SVG must be well-formed XML with no script, foreignObject, event-handler attributes, DOCTYPE, or absolute http(s) references.
The gateway serves icons via GET /api/plugin/task/:key/icon; the UI renders them only through <img>.

Billing

Plugins sharing a model may use their own usage schema and price. Administrators can set billing_setting.plugin_billing_expr keyed by <pluginKey>::<model>.

If the effective billing expression references a u() key absent from that plugin's usage schema, submission returns 400 model_price_error until compatible pricing is saved.

Routing and Channel Binding

Multiple plugins may claim the same model on the same host protocol path; candidates are ordered by ascending plugin key.
Type-61 "Task Plugin" channels bind via task_plugin_key.
Type-60 New API channels may bind several plugins via task_plugin_key / task_extend_plugin_keys.
Only a plugin declaring new_api can bind to a type-60 channel.

On this page