Skip to content

api-reference.md

Latest commit

 

History

History
130 lines (68 loc) · 5.9 KB

api-reference.md

File metadata and controls

130 lines (68 loc) · 5.9 KB
Raw

API Reference

Package Entrypoints

Entrypoint Purpose
aigc-provider-runtime-kit Combined runtime exports
aigc-provider-runtime-kit/core Provider, model, schema, and request body helpers
aigc-provider-runtime-kit/runninghub RunningHub catalog, descriptor, client, and key-pool helpers
aigc-provider-runtime-kit/runtime Explicit combined runtime exports

Core Helpers

defaultParameterSchemaForModel(capability, modelId, protocol?)

Returns a practical default parameter schema for image, video, audio, or chat models.

parseModelParameterSchema(value)

Accepts an object or JSON string and returns a safe model parameter schema. Invalid input returns an empty object.

mergeModelParameterSchema(capability, modelId, protocol, value)

Combines default model parameters with user or admin supplied overrides.

uiMetadataFromSchema(schemaValue, capability, inputCapabilitiesValue?)

Converts a parameter schema into UI-friendly metadata such as aspect ratios, default size, duration options, reference support, and input capability flags.

durationOptionsFromRange(range?)

Expands a duration range into sorted duration options.

isMultipartRequestBodyMode(value)

Checks whether a provider request mode should be treated as multipart form data.

buildProviderMultipartRequestBody(payload, fileFieldNamesValue)

Builds a FormData request body from scalar fields and file URL or data URL fields.

validateProviderDefinition(value) and validateProviderModelDefinition(value, providerIds?)

Return structured validation results with field paths, issue codes, and messages for provider or model configuration.

createProviderRegistry(input)

Creates an immutable provider/model registry after validating URLs, protocols, capabilities, duplicate IDs, and provider references. Invalid input throws ProviderRegistryValidationError with an issues array.

withRetry(operation, options?)

Runs an asynchronous operation with bounded exponential backoff, optional jitter, cancellation, custom retry decisions, and retry callbacks.

createOpenAICompatibleClient(options)

Creates a dependency-free JSON client for OpenAI-compatible APIs. It exposes request(path, body), createChatCompletion(body), and createImage(body). Request timeout, cancellation, custom headers, and opt-in retry policy are supported.

Failures use OpenAICompatibleError; isOpenAICompatibleError(value) safely narrows unknown errors.

RunningHub Helpers

normalizeRunningHubInputSlots(fields)

Converts RunningHub field definitions into reusable host-app input slot definitions.

buildRunningHubExecutionDescriptor(item)

Builds a host-app execution descriptor for RunningHub App or Workflow entries.

normalizeRunningHubCatalogItem(source)

Normalizes a source catalog record into a complete RunningHub catalog item.

createRunningHubClient(options)

Creates a minimal RunningHub submit/poll client. Host applications should wrap this client with their own permission, quota, credential, and audit layers.

Client options include requestTimeoutMs for individual HTTP requests and taskTimeoutMs for the complete polling lifecycle. Both have bounded defaults. runTask also accepts a per-task timeoutMs and an AbortSignal through signal.

RunningHubError and isRunningHubError(value)

RunningHub failures use a typed error with code, stage, optional HTTP status, and a retryable hint. Codes distinguish invalid configuration/input, cancellation, request or response failures, upstream rejection, task failure/timeout, unknown status, and missing output.

extractRunningHubOutputUrls(value)

Extracts image, video, and audio URLs from nested RunningHub result payloads.

acquireRunningHubKey(input) and releaseRunningHubKey(input)

Provide key-pool concurrency helpers against a Redis-like runtime interface.

acquireRunningHubKey accepts an optional leaseSeconds value between 30 seconds and 24 hours. Successful acquisitions refresh the counter lease.

orderRunningHubKeys(keys, preferredKeyId?)

Orders enabled keys by preferred key, default key, then other enabled keys.

Unified Runtime

createProviderRuntime(options)

Creates the unified execution entrypoint. It resolves enabled provider/model records, validates model input, selects the first supporting adapter, propagates cancellation and timeout signals, emits lifecycle events, and normalizes provider/model identity in the result.

ProviderAdapter

Adapters implement supports(provider, model) and execute(context). Adapter context includes provider/model definitions, validated input, cancellation signal, timeout, metadata, and a progress emitter.

createOpenAICompatibleAdapter(options)

Adapts the OpenAI-compatible client to unified runtime results. Chat text, image URLs/base64 data, and token usage are normalized automatically. Video/audio endpoints can be supplied through endpoints.

createRunningHubAdapter(options)

Adapts a RunningHub client to the unified runtime. It supports a custom resolveRunInput function or model advancedConfig.runninghub with target IDs and an input fieldMap.

validateProviderExecutionInput(model, input)

Validates required fields, scalar/array types, allowed options, numeric ranges, list maximums, and declared input capabilities.

ProviderRuntimeError and isProviderRuntimeError(value)

Distinguish missing/disabled configuration, provider-model mismatch, invalid input, missing adapters, adapter failures, and aborted/timed-out executions.

Runtime events

An optional hooks.onEvent handler receives started, validated, adapter-selected, progress, success, and failure events. Hook failures are isolated and never change execution behavior.

Stability

This is a 0.2.x pre-1.0 API. The unified runtime is ready for application integration, but breaking improvements remain possible before 1.0.