Eve library

ISIS v2 WS08-009: Audio API/SDK Contracts and Retrieval

Guide

Revision 1

On this page

Scope#

WS08-009 formalizes a first-class audio contract surface in Isis generation API and SDK so external systems can read normalized audio parameter contracts and artifact retrieval links without parsing generic job payloads.

Research and Existing Implementation Alignment#

Before implementation, existing audio contract coverage was audited:

  • API/SDK type contracts already included rich audio request/output payloads:
    • apps/isis/generation-api/src/types.ts
    • libs/isis/client/src/types.ts
  • Existing retrieval paths were generic-only:
    • GET /api/v1/jobs/:id
    • GET /api/v1/jobs/:id/output
  • RunPod audio endpoint classes were already implemented in WS08-008, so this task focused on retrieval contracts rather than provider routing.

This gap analysis confirmed the missing piece was a dedicated API + SDK contract for audio retrieval snapshots.

Deliverables#

  1. Audio contract snapshot schema and types
  • Added API and SDK interfaces for:
    • JobAudioContractParameters
    • JobAudioContractRetrievalLinks
    • JobAudioContractSnapshot
  • Added Zod schemas:
    • JobAudioContractParametersSchema
    • JobAudioContractRetrievalLinksSchema
    • JobAudioContractSnapshotSchema
  1. Dedicated API retrieval endpoint
  • Added GET /api/v1/jobs/:id/audio route in generation API.
  • Endpoint behavior:
    • returns normalized audio parameter contracts (audioConditioning, voiceConsistency, including snake_case aliases)
    • returns audio artifact retrieval links derived from output.audioPackage
    • returns 400 JOB_AUDIO_UNAVAILABLE when job has no audio context
    • returns 404 JOB_NOT_FOUND for missing jobs
  1. SDK method coverage for audio retrieval
  • Added GenerationResource methods:
    • getJobAudioContracts(jobId)
    • getJobAudioParameters(jobId)
    • getJobAudioPackage(jobId)
  1. API contract publication updates
  • Added /api/v1/jobs/{id}/audio to route inventory and OpenAPI spec with explicit JobAudioContractSnapshot schema reference.
  • Updated Isis API documentation and architecture/endpoint tables to include the new audio contract endpoint.
  1. Web parity exposure for new SDK methods
  • Updated GenerationParityPage method matrix and inspection console to expose:
    • getJobAudioContracts
    • getJobAudioParameters
    • getJobAudioPackage
  • Added parity tests to exercise these interactions in the UI.

Verification Commands#

bash
pnpm --filter @isis/generation-api exec vitest run src/routes/jobs.spec.ts src/schemas/job.schema.spec.ts --reporter=dot
pnpm --filter @isis/web exec vitest run src/pages/GenerationParityPage.spec.tsx --reporter=dot
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs

Result#

WS08-009 is implemented with explicit API/SDK contracts for audio parameters and retrieval, plus web parity exposure for all new SDK methods.