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.tslibs/isis/client/src/types.ts
- Existing retrieval paths were generic-only:
GET /api/v1/jobs/:idGET /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#
- Audio contract snapshot schema and types
- Added API and SDK interfaces for:
JobAudioContractParametersJobAudioContractRetrievalLinksJobAudioContractSnapshot
- Added Zod schemas:
JobAudioContractParametersSchemaJobAudioContractRetrievalLinksSchemaJobAudioContractSnapshotSchema
- Dedicated API retrieval endpoint
- Added
GET /api/v1/jobs/:id/audioroute 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_UNAVAILABLEwhen job has no audio context - returns
404 JOB_NOT_FOUNDfor missing jobs
- returns normalized audio parameter contracts (
- SDK method coverage for audio retrieval
- Added
GenerationResourcemethods:getJobAudioContracts(jobId)getJobAudioParameters(jobId)getJobAudioPackage(jobId)
- API contract publication updates
- Added
/api/v1/jobs/{id}/audioto route inventory and OpenAPI spec with explicitJobAudioContractSnapshotschema reference. - Updated Isis API documentation and architecture/endpoint tables to include the new audio contract endpoint.
- Web parity exposure for new SDK methods
- Updated
GenerationParityPagemethod matrix and inspection console to expose:getJobAudioContractsgetJobAudioParametersgetJobAudioPackage
- 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.