pi-media-models 0.1.0

package/src/adapters/openrouter.ts

@@ -0,0 +1,112 @@
+import { MediaError } from '../errors.js'
+import { MediaJob, mapJobState } from '../media-job.js'
+import { BaseAdapter, artifactsOrThrow, bearerHeaders, dataUris, makeModel, mergeOptions, requirePrompt } from './base.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, RemoteArtifact } from '../types.js'
+
+const IMAGE_CAPS: Capability[] = ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
+const VIDEO_CAPS: Capability[] = ['video.text_to_video', 'video.image_to_video', 'video.reference', 'video.native_audio']
+
+export class OpenRouterAdapter extends BaseAdapter {
+  readonly id = 'openrouter'
+  readonly displayName = 'OpenRouter'
+  readonly envKey = 'OPENROUTER_API_KEY'
+  private readonly baseUrl = 'https://openrouter.ai/api/v1'
+
+  models(): ModelDescriptor[] {
+    return [
+      makeModel(this.id, 'multi-vendor', '<OpenRouter image model>', IMAGE_CAPS, 'Use /images/models endpoint externally to choose a current image model'),
+      makeModel(this.id, 'multi-vendor', '<OpenRouter video model>', VIDEO_CAPS, 'Availability and parameters vary by upstream endpoint'),
+      makeModel(this.id, 'multi-vendor', '<OpenRouter TTS model>', ['speech.tts']),
+    ]
+  }
+
+  supports(capability: Capability): boolean {
+    return IMAGE_CAPS.includes(capability) || VIDEO_CAPS.includes(capability) || capability === 'speech.tts'
+  }
+
+  async execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    this.assertSupport(request)
+    if (request.capability.startsWith('image.')) return this.image(request, context)
+    if (request.capability.startsWith('video.')) return this.video(request, context)
+    return this.tts(request, context)
+  }
+
+  private async image(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    const key = this.key(request)
+    const references = [request.inputImage, ...(request.referenceImages ?? [])].filter((value): value is string => Boolean(value))
+    const inputReferences = await dataUris(this.input, references, context.signal)
+    if (inputReferences.length > 16) throw new MediaError('INPUT', 'OpenRouter Images API supports at most 16 input references', { provider: this.id })
+    const payload = mergeOptions({
+      model: request.model,
+      prompt: requirePrompt(request),
+      n: request.count ?? 1,
+      ...(inputReferences.length ? { input_references: inputReferences } : {}),
+      ...(request.aspectRatio ? { aspect_ratio: request.aspectRatio } : {}),
+      ...(request.resolution ? { resolution: request.resolution } : {}),
+      ...(request.seed !== undefined ? { seed: request.seed } : {}),
+    }, request.providerOptions)
+    const data = await this.http.json<unknown>(`${this.baseUrl}/images`, {
+      method: 'POST', headers: bearerHeaders(key, { 'Content-Type': 'application/json' }), body: JSON.stringify(payload),
+      signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 180_000,
+    })
+    return artifactsOrThrow(this.result(request, data, 'image'))
+  }
+
+  private async tts(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    const key = this.key(request)
+    const format = request.responseFormat ?? 'mp3'
+    const payload = mergeOptions({
+      model: request.model, input: request.text ?? request.prompt ?? '', voice: request.voice ?? 'alloy', response_format: format,
+    }, request.providerOptions)
+    const response = await this.http.request(`${this.baseUrl}/audio/speech`, {
+      method: 'POST', headers: bearerHeaders(key, { 'Content-Type': 'application/json' }), body: JSON.stringify(payload),
+      signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 180_000,
+    })
+    const base64 = Buffer.from(await response.arrayBuffer()).toString('base64')
+    return this.result(request, { b64_json: base64, mime_type: response.headers.get('content-type') ?? `audio/${format}` }, 'audio')
+  }
+
+  private async video(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    const key = this.key(request)
+    const refs = [request.inputImage, ...(request.referenceImages ?? [])].filter((value): value is string => Boolean(value))
+    const inputReferences = await dataUris(this.input, refs, context.signal)
+    const payload: JsonObject = mergeOptions({
+      model: request.model,
+      prompt: requirePrompt(request),
+      ...(inputReferences.length ? { input_references: inputReferences } : {}),
+      ...(request.duration ? { duration: request.duration } : {}),
+      ...(request.resolution ? { resolution: request.resolution } : {}),
+      ...(request.aspectRatio ? { aspect_ratio: request.aspectRatio } : {}),
+      ...(request.generateAudio !== undefined ? { generate_audio: request.generateAudio } : {}),
+    }, request.providerOptions)
+    const submitted = await this.http.json<Record<string, unknown>>(`${this.baseUrl}/videos`, {
+      method: 'POST', headers: bearerHeaders(key, { 'Content-Type': 'application/json' }), body: JSON.stringify(payload),
+      signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 60_000,
+    })
+    const jobId = typeof submitted.id === 'string' ? submitted.id : typeof submitted.job_id === 'string' ? submitted.job_id : undefined
+    if (!jobId) return artifactsOrThrow(this.result(request, submitted, 'video'))
+    const job = new MediaJob<Record<string, unknown>>({
+      id: jobId, provider: this.id, signal: context.signal, timeoutMs: timeout(request), minDelayMs: 5_000, maxDelayMs: 30_000,
+      onProgress: status => context.onProgress?.(`OpenRouter ${jobId}: ${status.state}`),
+      poll: async signal => {
+        const status = await this.http.json<Record<string, unknown>>(`${this.baseUrl}/videos/${encodeURIComponent(jobId)}`, {
+          headers: bearerHeaders(key), signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+        })
+        const state = mapJobState(status.status)
+        return { state, ...(state === 'succeeded' ? { result: status } : {}), ...(typeof status.error === 'string' ? { message: status.error } : {}) } satisfies JobStatus<Record<string, unknown>>
+      },
+    })
+    const completed = await job.wait()
+    const result = this.result(request, completed, 'video', { jobId })
+    if (result.artifacts.length === 0) {
+      const artifact: RemoteArtifact = { kind: 'video', url: `${this.baseUrl}/videos/${encodeURIComponent(jobId)}/content`, headers: bearerHeaders(key) }
+      result.artifacts.push(artifact)
+    }
+    return result
+  }
+}
+
+function timeout(request: MediaRequest): number {
+  const value = request.providerOptions?.timeoutMs
+  return typeof value === 'number' && value > 0 ? value : 40 * 60_000
+}

package/src/adapters/xai.ts

@@ -0,0 +1,122 @@
+import { MediaError } from '../errors.js'
+import { MediaJob, mapJobState } from '../media-job.js'
+import { BaseAdapter, artifactsOrThrow, bearerHeaders, dataUris, makeModel, mergeOptions, requirePrompt } from './base.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor } from '../types.js'
+
+const IMAGE_CAPS: Capability[] = ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
+const VIDEO_CAPS: Capability[] = ['video.text_to_video', 'video.image_to_video', 'video.reference', 'video.edit', 'video.extend', 'video.native_audio']
+
+export class XAIAdapter extends BaseAdapter {
+  readonly id = 'xai'
+  readonly displayName = 'xAI / Grok Imagine'
+  readonly envKey = 'XAI_API_KEY'
+  private readonly baseUrl = 'https://api.x.ai/v1'
+
+  models(): ModelDescriptor[] {
+    return [
+      makeModel(this.id, 'xai', 'grok-imagine-image-2.0', IMAGE_CAPS),
+      makeModel(this.id, 'xai', 'grok-imagine-video-1.5', VIDEO_CAPS.filter(capability => capability !== 'video.edit' && capability !== 'video.extend'), 'T2V/I2V supports 1080p; reference-to-video is capped at 720p'),
+      makeModel(this.id, 'xai', 'grok-imagine-video', ['video.edit', 'video.extend'], 'Current official edit/extend examples use this model id'),
+    ]
+  }
+
+  supports(capability: Capability, model: string): boolean {
+    if (capability.startsWith('image.')) return /image/i.test(model)
+    if (capability.startsWith('video.')) {
+      if (!/video/i.test(model) || !VIDEO_CAPS.includes(capability)) return false
+      if (/video-1\.5$/i.test(model) && ['video.edit', 'video.extend'].includes(capability)) return false
+      return true
+    }
+    return false
+  }
+
+  async execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    this.assertSupport(request)
+    return request.capability.startsWith('image.') ? this.image(request, context) : this.video(request, context)
+  }
+
+  private async image(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    const key = this.key(request)
+    const sources = [request.inputImage, ...(request.referenceImages ?? [])].filter((value): value is string => Boolean(value))
+    const editing = request.capability !== 'image.text_to_image' || sources.length > 0
+    const images = await dataUris(this.input, sources, context.signal)
+    if (images.length > 5) throw new MediaError('INPUT', 'xAI image editing supports at most 5 source images', { provider: this.id })
+    const payload = mergeOptions({
+      model: request.model,
+      prompt: requirePrompt(request),
+      ...(editing ? { images: images.map(url => ({ url })) } : {}),
+      ...(request.aspectRatio ? { aspect_ratio: request.aspectRatio } : {}),
+      ...(request.resolution ? { resolution: request.resolution } : {}),
+      ...(request.count ? { n: request.count } : {}),
+      response_format: 'url',
+    }, request.providerOptions)
+    const data = await this.http.json<unknown>(`${this.baseUrl}/images/${editing ? 'edits' : 'generations'}`, {
+      method: 'POST', headers: bearerHeaders(key, { 'Content-Type': 'application/json' }), body: JSON.stringify(payload),
+      signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 180_000,
+    })
+    return artifactsOrThrow(this.result(request, data, 'image'))
+  }
+
+  private async video(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
+    const key = this.key(request)
+    const operation = request.operation ?? capabilityOperation(request.capability)
+    const path = operation === 'edit' ? 'edits' : operation === 'extend' ? 'extensions' : 'generations'
+    const image = request.inputImage ? await this.input.asDataUri(request.inputImage, context.signal) : undefined
+    const video = request.inputVideo ? await this.input.asDataUri(request.inputVideo, context.signal) : undefined
+    const referenceImages = await dataUris(this.input, request.referenceImages, context.signal)
+    const referenceAudios = await dataUris(this.input, request.referenceAudios, context.signal)
+    if (request.referenceVideos?.length) throw new MediaError('CAPABILITY_UNSUPPORTED', 'xAI reference-to-video does not document reference video inputs', { provider: this.id })
+    if (operation === 'reference' && referenceImages.length > 7) {
+      throw new MediaError('INPUT', 'xAI reference-to-video supports at most 7 reference images', { provider: this.id })
+    }
+    if ((operation === 'edit' || operation === 'extend') && !video) {
+      throw new MediaError('INPUT', `xAI video ${operation} requires inputVideo`, { provider: this.id })
+    }
+    const base: JsonObject = {
+      model: request.model,
+      prompt: requirePrompt(request),
+      ...(video ? { video: { url: video } } : {}),
+      ...(image ? { image: { url: image } } : {}),
+      ...(referenceImages.length ? { reference_images: referenceImages.map(url => ({ url })) } : {}),
+      ...(referenceAudios.length ? { reference_audios: referenceAudios.map(url => ({ url })) } : {}),
+      ...((operation !== 'edit') && request.duration ? { duration: request.duration } : {}),
+      ...((operation !== 'edit') && request.aspectRatio ? { aspect_ratio: request.aspectRatio } : {}),
+      ...((operation !== 'edit') && request.resolution ? { resolution: request.resolution } : {}),
+      ...(request.generateAudio !== undefined ? { generate_audio: request.generateAudio } : {}),
+    }
+    const submitted = await this.http.json<Record<string, unknown>>(`${this.baseUrl}/videos/${path}`, {
+      method: 'POST', headers: bearerHeaders(key, { 'Content-Type': 'application/json' }), body: JSON.stringify(mergeOptions(base, request.providerOptions)),
+      signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 60_000,
+    })
+    const requestId = typeof submitted.request_id === 'string' ? submitted.request_id : undefined
+    if (!requestId) return artifactsOrThrow(this.result(request, submitted, 'video'))
+    const job = new MediaJob<Record<string, unknown>>({
+      id: requestId, provider: this.id, signal: context.signal, timeoutMs: timeout(request), minDelayMs: 1_000, maxDelayMs: 8_000,
+      onProgress: status => context.onProgress?.(`xAI ${requestId}: ${status.state}`),
+      poll: async signal => {
+        const status = await this.http.json<Record<string, unknown>>(`${this.baseUrl}/videos/${encodeURIComponent(requestId)}`, {
+          headers: bearerHeaders(key), signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+        })
+        const state = mapJobState(status.status)
+        const error = status.error && typeof status.error === 'object'
+          ? JSON.stringify(status.error)
+          : typeof status.error === 'string' ? status.error : undefined
+        return { state, ...(state === 'succeeded' ? { result: status } : {}), ...(error ? { message: error } : {}) } satisfies JobStatus<Record<string, unknown>>
+      },
+    })
+    const completed = await job.wait()
+    return artifactsOrThrow(this.result(request, completed, 'video', { jobId: requestId }))
+  }
+}
+
+function capabilityOperation(capability: Capability): string {
+  if (capability === 'video.edit') return 'edit'
+  if (capability === 'video.extend') return 'extend'
+  if (capability === 'video.reference') return 'reference'
+  return 'generate'
+}
+
+function timeout(request: MediaRequest): number {
+  const value = request.providerOptions?.timeoutMs
+  return typeof value === 'number' && value > 0 ? value : 15 * 60_000
+}

package/src/artifacts.ts

@@ -0,0 +1,130 @@
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { extname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { HttpClient } from './http.js'
+import { MediaError } from './errors.js'
+import type { MediaKind, NormalizedArtifact, RemoteArtifact } from './types.js'
+
+const EXT_BY_MIME: Record<string, string> = {
+  'audio/aac': '.aac', 'audio/flac': '.flac', 'audio/L16': '.pcm', 'audio/mpeg': '.mp3', 'audio/mp4': '.m4a',
+  'audio/ogg': '.ogg', 'audio/pcm': '.pcm', 'audio/wav': '.wav', 'image/gif': '.gif', 'image/jpeg': '.jpg',
+  'image/png': '.png', 'image/webp': '.webp', 'video/mp4': '.mp4', 'video/mpeg': '.mpeg',
+  'video/quicktime': '.mov', 'video/webm': '.webm',
+}
+
+function kindFrom(value: string, fallback: MediaKind): MediaKind {
+  const lower = value.toLowerCase()
+  if (/\.(?:png|jpe?g|gif|webp)(?:[?#]|$)/.test(lower) || lower.startsWith('image/')) return 'image'
+  if (/\.(?:mp4|mov|webm|mkv|mpeg)(?:[?#]|$)/.test(lower) || lower.startsWith('video/')) return 'video'
+  if (/\.(?:mp3|wav|ogg|m4a|aac|flac)(?:[?#]|$)/.test(lower) || lower.startsWith('audio/')) return 'audio'
+  return fallback
+}
+
+function looksLikeBase64(value: string): boolean {
+  return value.length > 100 && value.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(value)
+}
+
+export function extractArtifacts(payload: unknown, fallback: MediaKind): RemoteArtifact[] {
+  const found: RemoteArtifact[] = []
+  const seen = new Set<string>()
+
+  function push(artifact: RemoteArtifact): void {
+    const identity = artifact.url ?? artifact.base64
+    if (!identity || seen.has(identity)) return
+    seen.add(identity)
+    found.push(artifact)
+  }
+
+  function walk(value: unknown, key = '', mimeHint?: string): void {
+    if (typeof value === 'string') {
+      if (/^https?:\/\//i.test(value)) push({ kind: kindFrom(value, mimeHint ? kindFrom(mimeHint, fallback) : fallback), url: value, ...(mimeHint ? { mimeType: mimeHint } : {}) })
+      else if (value.startsWith('data:')) {
+        const match = /^data:([^;,]+)?;base64,(.*)$/s.exec(value)
+        if (match?.[2]) push({ kind: kindFrom(match[1] ?? '', fallback), base64: match[2], ...(match[1] ? { mimeType: match[1] } : {}) })
+      } else if (/(?:b64|base64|bytes|data|content)/i.test(key) && looksLikeBase64(value)) {
+        push({ kind: kindFrom(mimeHint ?? '', fallback), base64: value, ...(mimeHint ? { mimeType: mimeHint } : {}) })
+      }
+      return
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, key, mimeHint)
+      return
+    }
+    if (!value || typeof value !== 'object') return
+    const object = value as Record<string, unknown>
+    const mime = typeof object.mime_type === 'string'
+      ? object.mime_type
+      : typeof object.mimeType === 'string'
+        ? object.mimeType
+        : mimeHint
+    for (const [childKey, child] of Object.entries(object)) walk(child, childKey, mime)
+  }
+
+  walk(payload)
+  return found
+}
+
+function inferExtension(artifact: RemoteArtifact): string {
+  if (artifact.fileName) {
+    const extension = extname(artifact.fileName)
+    if (extension) return extension
+  }
+  if (artifact.mimeType) {
+    const baseMime = artifact.mimeType.split(';', 1)[0] ?? artifact.mimeType
+    const known = EXT_BY_MIME[baseMime]
+    if (known) return known
+  }
+  if (artifact.url) {
+    const extension = extname(new URL(artifact.url).pathname)
+    if (extension && extension.length <= 8) return extension
+  }
+  return artifact.kind === 'image' ? '.png' : artifact.kind === 'video' ? '.mp4' : artifact.kind === 'audio' ? '.mp3' : '.txt'
+}
+
+export class ArtifactDownloader {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly outputDir = join(homedir(), '.pi', 'agent', 'media', 'outputs'),
+  ) {}
+
+  async downloadAll(artifacts: readonly RemoteArtifact[], signal?: AbortSignal): Promise<NormalizedArtifact[]> {
+    await mkdir(this.outputDir, { recursive: true })
+    const outputs: NormalizedArtifact[] = []
+    for (const artifact of artifacts) outputs.push(await this.download(artifact, signal))
+    return outputs
+  }
+
+  private async download(artifact: RemoteArtifact, signal?: AbortSignal): Promise<NormalizedArtifact> {
+    const extension = inferExtension(artifact)
+    const finalPath = join(this.outputDir, `${Date.now()}-${randomUUID().slice(0, 8)}${extension}`)
+    const partPath = `${finalPath}.part`
+    try {
+      let bytes: Uint8Array
+      let mimeType = artifact.mimeType
+      if (artifact.base64) {
+        bytes = Buffer.from(artifact.base64, 'base64')
+      } else if (artifact.url) {
+        const response = await this.http.request(artifact.url, {
+          signal,
+          headers: artifact.headers,
+          timeoutMs: 120_000,
+          retries: 2,
+          provider: 'download',
+        })
+        bytes = new Uint8Array(await response.arrayBuffer())
+        mimeType ??= response.headers.get('content-type')?.split(';', 1)[0] ?? undefined
+      } else {
+        throw new MediaError('DOWNLOAD', 'Artifact has neither URL nor base64 data')
+      }
+      await writeFile(partPath, bytes)
+      await rename(partPath, finalPath)
+      const info = await stat(finalPath)
+      return { kind: artifact.kind, path: finalPath, bytes: info.size, ...(mimeType ? { mimeType } : {}) }
+    } catch (error) {
+      await rm(partPath, { force: true }).catch(() => undefined)
+      if (error instanceof MediaError) throw error
+      throw new MediaError('DOWNLOAD', `Failed to save generated ${artifact.kind}`, { cause: error })
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { CAPABILITIES, type Capability, type JsonObject } from './types.js'
+import { MediaError } from './errors.js'
+
+export interface CustomAsyncConfig {
+  idPath: string
+  statusPath: string
+  pollEndpoint: string
+  resultPath?: string
+  cancelEndpoint?: string
+  successValues?: string[]
+  failureValues?: string[]
+}
+
+export interface CustomEndpointConfig {
+  path: string
+  method?: string
+  format?: 'json' | 'multipart'
+  async?: CustomAsyncConfig
+}
+
+export interface CustomModelConfig {
+  id: string
+  vendor: string
+  capabilities: Capability[]
+  endpoints: Partial<Record<Capability, string | CustomEndpointConfig>>
+}
+
+export interface CustomProviderConfig {
+  id: string
+  name?: string
+  baseUrl: string
+  apiKeyEnv: string
+  auth?: 'bearer' | 'x-api-key' | 'none'
+  headers?: Record<string, string>
+  models: CustomModelConfig[]
+}
+
+export interface MediaConfig {
+  outputDir?: string
+  customProviders: CustomProviderConfig[]
+  providerOptions?: Record<string, JsonObject>
+}
+
+const EMPTY_CONFIG: MediaConfig = { customProviders: [] }
+
+async function parseFile(path: string): Promise<Partial<MediaConfig> | undefined> {
+  try {
+    const value = JSON.parse(await readFile(path, 'utf8')) as unknown
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('expected JSON object')
+    return value as Partial<MediaConfig>
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw new MediaError('CONFIG', `Invalid media config ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error })
+  }
+}
+
+export async function loadMediaConfig(cwd: string, allowProjectConfig: boolean): Promise<MediaConfig> {
+  const globalPath = join(homedir(), '.pi', 'agent', 'media-models.json')
+  const global = await parseFile(globalPath) ?? EMPTY_CONFIG
+  const project = allowProjectConfig ? await parseFile(join(cwd, '.pi', 'media-models.json')) : undefined
+  const merged: MediaConfig = {
+    outputDir: project?.outputDir ?? global.outputDir,
+    customProviders: project?.customProviders ?? global.customProviders ?? [],
+    providerOptions: { ...(global.providerOptions ?? {}), ...(project?.providerOptions ?? {}) },
+  }
+  validateCustomProviders(merged.customProviders)
+  return merged
+}
+
+function validateCustomProviders(providers: CustomProviderConfig[]): void {
+  const ids = new Set<string>()
+  for (const provider of providers) {
+    if (!provider.id || !provider.baseUrl || !provider.apiKeyEnv || !Array.isArray(provider.models)) {
+      throw new MediaError('CONFIG', 'Each custom provider requires id, baseUrl, apiKeyEnv, and models[]')
+    }
+    if (ids.has(provider.id)) throw new MediaError('CONFIG', `Duplicate custom provider id: ${provider.id}`)
+    ids.add(provider.id)
+    if (['openrouter', 'fal', 'dashscope', 'qwencloud', 'openai', 'gemini', 'vertex', 'xai', 'atlas'].includes(provider.id)) {
+      throw new MediaError('CONFIG', `Custom provider id conflicts with built-in provider: ${provider.id}`)
+    }
+    for (const model of provider.models) {
+      if (!model.id || !model.vendor || !model.capabilities?.length || !model.endpoints) {
+        throw new MediaError('CONFIG', `Custom provider ${provider.id} model requires id, vendor, capabilities, endpoints`)
+      }
+      for (const capability of model.capabilities) {
+        if (!(CAPABILITIES as readonly string[]).includes(capability)) throw new MediaError('CONFIG', `Unknown capability ${capability} in ${provider.id}/${model.id}`)
+        if (!model.endpoints[capability]) throw new MediaError('CONFIG', `${provider.id}/${model.id} declares ${capability} without an endpoint`)
+      }
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,61 @@
+export type MediaErrorCode =
+  | 'ABORTED'
+  | 'AUTH'
+  | 'CAPABILITY_UNSUPPORTED'
+  | 'CONFIG'
+  | 'DOWNLOAD'
+  | 'HTTP'
+  | 'INPUT'
+  | 'PROVIDER'
+  | 'RATE_LIMITED'
+  | 'TIMEOUT'
+
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9_-]{8,}|Bearer\s+[A-Za-z0-9._~+/=-]{8,}|(?:api[_-]?key|token)["'\s:=]+[A-Za-z0-9._~+/=-]{8,})/gi
+
+export function redactSecrets(value: string, secrets: readonly string[] = []): string {
+  let output = value
+  for (const secret of secrets) {
+    if (secret.length >= 4) output = output.split(secret).join('[REDACTED]')
+  }
+  return output.replace(SECRET_PATTERN, match => {
+    const prefix = match.match(/^(Bearer\s+|(?:api[_-]?key|token)["'\s:=]+)/i)?.[0] ?? ''
+    return `${prefix}[REDACTED]`
+  })
+}
+
+export class MediaError extends Error {
+  readonly code: MediaErrorCode
+  readonly provider?: string
+  readonly status?: number
+  readonly retryAfterMs?: number
+  override readonly cause?: unknown
+
+  constructor(
+    code: MediaErrorCode,
+    message: string,
+    options: {
+      provider?: string
+      status?: number
+      retryAfterMs?: number
+      cause?: unknown
+      secrets?: readonly string[]
+    } = {},
+  ) {
+    super(redactSecrets(message, options.secrets))
+    this.name = 'MediaError'
+    this.code = code
+    if (options.provider !== undefined) this.provider = options.provider
+    if (options.status !== undefined) this.status = options.status
+    if (options.retryAfterMs !== undefined) this.retryAfterMs = options.retryAfterMs
+    if (options.cause !== undefined) this.cause = options.cause
+  }
+}
+
+export function asMediaError(error: unknown, provider?: string): MediaError {
+  if (error instanceof MediaError) return error
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    return new MediaError('ABORTED', 'Media request aborted', { provider, cause: error })
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  return new MediaError('PROVIDER', message, { provider, cause: error })
+}

package/src/http.ts

@@ -0,0 +1,131 @@
+import { MediaError, redactSecrets } from './errors.js'
+
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+
+export interface HttpRequestOptions extends RequestInit {
+  timeoutMs?: number
+  retries?: number
+  retryUnsafe?: boolean
+  provider?: string
+  secrets?: readonly string[]
+}
+
+function retryAfterMs(headers: Headers): number | undefined {
+  const raw = headers.get('retry-after')
+  if (!raw) return undefined
+  const seconds = Number(raw)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
+  const date = Date.parse(raw)
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined
+}
+
+function combineSignals(signal: AbortSignal | null | undefined, timeoutMs: number): { signal: AbortSignal; cleanup: () => void } {
+  const timeoutController = new AbortController()
+  const timer = setTimeout(() => timeoutController.abort(new DOMException('Request timed out', 'TimeoutError')), timeoutMs)
+  const combined = signal ? AbortSignal.any([signal, timeoutController.signal]) : timeoutController.signal
+  return { signal: combined, cleanup: () => clearTimeout(timer) }
+}
+
+async function sleep(ms: number, signal?: AbortSignal | null): Promise<void> {
+  if (ms <= 0) return
+  await new Promise<void>((resolve, reject) => {
+    const done = () => {
+      signal?.removeEventListener('abort', abort)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    const abort = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+      reject(new DOMException('Aborted', 'AbortError'))
+    }
+    if (signal?.aborted) return abort()
+    signal?.addEventListener('abort', abort, { once: true })
+  })
+}
+
+export class HttpClient {
+  private readonly fetchImpl: FetchLike
+
+  constructor(fetchImpl?: FetchLike) {
+    if (!fetchImpl && process.env.PI_MEDIA_TEST_MODE === '1') {
+      this.fetchImpl = async () => {
+        throw new MediaError('CONFIG', 'Real network requests are disabled in tests')
+      }
+    } else {
+      this.fetchImpl = fetchImpl ?? globalThis.fetch.bind(globalThis)
+    }
+  }
+
+  async request(url: string, options: HttpRequestOptions = {}): Promise<Response> {
+    const {
+      timeoutMs = 30_000,
+      retries = 2,
+      retryUnsafe = false,
+      provider,
+      secrets = [],
+      ...init
+    } = options
+    const method = (init.method ?? 'GET').toUpperCase()
+    const canRetry = retryUnsafe || method === 'GET' || method === 'HEAD'
+    let attempt = 0
+
+    while (true) {
+      const { signal, cleanup } = combineSignals(init.signal, timeoutMs)
+      try {
+        const response = await this.fetchImpl(url, { ...init, signal })
+        if (response.ok) return response
+
+        const retryMs = retryAfterMs(response.headers)
+        const retryable = response.status === 429 || response.status >= 500
+        if (retryable && canRetry && attempt < retries) {
+          attempt += 1
+          await response.body?.cancel().catch(() => undefined)
+          await sleep(retryMs ?? Math.min(500 * 2 ** (attempt - 1), 5_000), init.signal)
+          continue
+        }
+
+        const body = redactSecrets((await response.text().catch(() => '')).slice(0, 2_000), secrets)
+        const code = response.status === 401 || response.status === 403
+          ? 'AUTH'
+          : response.status === 429
+            ? 'RATE_LIMITED'
+            : 'HTTP'
+        throw new MediaError(code, `${provider ?? 'Provider'} HTTP ${response.status}${body ? `: ${body}` : ''}`, {
+          provider,
+          status: response.status,
+          ...(retryMs === undefined ? {} : { retryAfterMs: retryMs }),
+          secrets,
+        })
+      } catch (error) {
+        if (error instanceof MediaError) throw error
+        if (init.signal?.aborted) throw new MediaError('ABORTED', 'Media request aborted', { provider, cause: error })
+        if (signal.aborted) throw new MediaError('TIMEOUT', `Request timed out after ${timeoutMs}ms`, { provider, cause: error })
+        if (canRetry && attempt < retries) {
+          attempt += 1
+          await sleep(Math.min(500 * 2 ** (attempt - 1), 5_000), init.signal)
+          continue
+        }
+        throw new MediaError('HTTP', `Network request failed: ${error instanceof Error ? error.message : String(error)}`, {
+          provider,
+          cause: error,
+          secrets,
+        })
+      } finally {
+        cleanup()
+      }
+    }
+  }
+
+  async json<T>(url: string, options: HttpRequestOptions = {}): Promise<T> {
+    const response = await this.request(url, options)
+    try {
+      return await response.json() as T
+    } catch (error) {
+      throw new MediaError('PROVIDER', `${options.provider ?? 'Provider'} returned invalid JSON`, {
+        provider: options.provider,
+        cause: error,
+      })
+    }
+  }
+}