Skip to content

feat: add effort to SpeakerIdentificationRequest - #168

Merged
MLawlz merged 2 commits into
mainfrom
matt/speaker-identification-effort
Aug 12, 2026
Merged

feat: add effort to SpeakerIdentificationRequest#168
MLawlz merged 2 commits into
mainfrom
matt/speaker-identification-effort

Conversation

@MLawlz

@MLawlz MLawlz commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Fixes #167.

Problem

The speaker identification docs document an effort field under speech_understanding.request.speaker_identification, but SpeakerIdentificationRequest doesn't declare it, so TypeScript users can't set it without casting:

await client.transcripts.submit({
  audio_url: audioUrl,
  speaker_labels: true,
  speech_understanding: {
    request: {
      speaker_identification: {
        speaker_type: "name",
        effort: "medium", // TS2353: Object literal may only specify known properties
      },
    },
  },
});

Change

  • Add SpeakerIdentificationEffort ("low" | "medium") and an optional effort field on SpeakerIdentificationRequest, defaulting to "low" server-side, per the docs.
  • Add tests/unit/speaker-identification.test.ts covering the field serializing into the request body, the field being omitted when unset, and both documented values type checking.
  • CHANGELOG entry + patch version bump.

Type-only, additive, and backward compatible — effort is optional, so existing code is unaffected.

Note for maintainers

src/types/openapi.generated.ts is generated from the internal OpenAPI spec, which I don't have access to. This edits the generated file directly, so the spec needs the same field added upstream or the next pnpm generate:types run will drop it.

One thing worth confirming separately (out of scope here): the docs describe the speaker list as speakers, an array of objects ({ name } / { role } / description / arbitrary custom keys), while the SDK type has known_values?: string[]. If the docs are current, that type is stale too and users following the docs will hit the same class of error. Happy to follow up with a PR once someone confirms which shape the API takes.

Testing

  • tests/unit/speaker-identification.test.ts — 3 passed
  • Full unit suite: 197 passed, 3 failed — all failures pre-exist on main and are unrelated (utils.test.ts runtime_env=Node/ assertions under local Node 24, and a WritableStream type mismatch in realtime.test.ts)
  • pnpm lint (eslint + tsc + publint) and pnpm build pass; the remaining prettier --check warnings are pre-existing on main in files this PR doesn't touch

🤖 Generated with Claude Code

The speaker identification API accepts an `effort` field ("low" | "medium",
default "low") to trade cost for quality on harder audio, but it was missing
from the SDK types, so setting it failed to type check.

Fixes #167

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread src/types/openapi.generated.ts Outdated
/**
* Effort level for speaker identification
*/
export type SpeakerIdentificationEffort = "low" | "medium";

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

effort should be for all llm speech understanding tasks, and all tasks can take it

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be addressed now @jhazenaai so would love another review when you have a sec

Address review: effort isn't speaker-identification specific — every LLM
speech understanding task accepts it. Rename the enum to
SpeechUnderstandingEffort and add the field to TranslationRequest and
CustomFormattingRequest alongside SpeakerIdentificationRequest.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread CHANGELOG.md

## [4.36.6]

- Add `effort` to the speech understanding feature requests (`SpeakerIdentificationRequest`, `TranslationRequest`, `CustomFormattingRequest`) — `"low"` (default) or `"medium"`, set per task, typed as the new `SpeechUnderstandingEffort`. The field was already accepted by the API but missing from the SDK types, so setting it failed to type check

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summarization & Action items missing. Can add in a follow up.

@MLawlz
MLawlz merged commit 5e361e7 into main Aug 12, 2026
3 checks passed
@MLawlz
MLawlz deleted the matt/speaker-identification-effort branch August 12, 2026 23:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add SpeakerIdentificationRequest.effort type

2 participants