fix: align Clip + Voice contracts with the live gateway - #48
Conversation
Verified by probing api.wave.online: ClipCreate previously required the
rejected numeric videoId/startTime/endTime shape; the gateway accepts
{ source: "<recording-id>", in: "5s", out: "10s" }. The voice path is
POST /voice (not /voice/generate), requiring only text, and the primary
200 returns raw audio/mpeg bytes.
- ClipCreate: source (recording id string) + in/out relative time strings.
- /voice/generate -> /voice; VoiceGenerateRequest.text required, voiceId
optional (also sent as voice_id).
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_4433be5b-ea99-4ac6-9085-eb4bb1bdfe31) |
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 3 minutes Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Comment |
ApprovabilityVerdict: Needs human review This PR introduces explicitly labeled BREAKING changes to API schemas (endpoint rename, field type changes) that will break existing SDK clients. An unresolved comment about the missing version bump for semver compliance, combined with a Medium-severity finding about the voiceId/voice_id alias constraint, warrants human review. You can customize Macroscope's approvability policy. Learn more. |
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
PR Summary by QodoFix OpenAPI ClipCreate + Voice endpoints to match live gateway
AI Description
Diagram
High-Level Assessment
Files changed (2)
|
|
Running ultrareview automatically — This PR makes significant changes to the Clip and Voice API contracts—replacing required fields, altering endpoint paths, and updating response types—which risk breaking client integrations if any detail is misaligned with the live gateway.. I'll post findings when complete. |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| required: [source, in, out] | ||
| properties: | ||
| videoId: | ||
| source: | ||
| type: string | ||
| startTime: | ||
| type: number | ||
| endTime: | ||
| type: number | ||
| description: Recording id the clip is cut from (e.g. `rec_abc123`). Verified against the live gateway — the older `{ type, id, start_time, end_time }` source object is rejected. | ||
| in: | ||
| type: string | ||
| description: Start offset as a relative time string, e.g. `5s` or `2m`. | ||
| out: | ||
| type: string | ||
| description: End offset as a relative time string, e.g. `10s` or `1m30s`. |
There was a problem hiding this comment.
🔍 Clip response and update schemas still use the old numeric time contract
ClipCreate was migrated to { source, in, out } string offsets, but Clip (openapi.yaml:2201-2237) and ClipUpdate (openapi.yaml:2256-2266) still declare videoId, startTime, endTime as numbers. If the live gateway really rejects the numeric shape on create, PATCH /clips/{clipId} (which sends startTime/endTime numbers) and the documented clip response shape are likely also out of sync. Worth probing the gateway for the read/update shapes so the whole Clips surface is consistent, otherwise generated SDKs will still produce rejected PATCH bodies.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Only the ClipCreate request shape was verified against the live gateway; rewriting the Clip response and ClipUpdate schemas without probing the read/update endpoints (which requires gateway credentials unavailable here) would risk documenting an unverified contract.
| in: | ||
| type: string | ||
| description: Start offset as a relative time string, e.g. `5s` or `2m`. |
There was a problem hiding this comment.
🔍 Property named in may collide with reserved words in generated SDKs
in/out are fine in JSON Schema, but in is a reserved keyword in several target languages used by openapi-generator (Python/JS in operator contexts, Go in is fine, C#/Java in). Generators usually escape it, but the resulting SDK field names may be mangled (e.g. _in, varIn). Worth a quick generation check with the typescript-fetch generator documented in README before publishing.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
in/out are the live gateway's wire field names, so the spec must keep them; openapi-generator escapes reserved keywords in generated SDKs without affecting the wire format, making this a generator-side cosmetic concern, not a spec defect.
| $ref: '#/components/schemas/Voice' | ||
|
|
||
| /voice/generate: | ||
| /voice: |
There was a problem hiding this comment.
🔍 Breaking path rename with no version bump or deprecated alias
/voice/generate → /voice removes the old path entirely (CHANGELOG explains the gateway does not serve it), but info.version remains 1.0.0 (openapi.yaml:24) despite the CHANGELOG labelling this a BREAKING change and the project claiming SemVer adherence. Existing generated clients calling generateSpeech will 404 with no transition period; consider bumping the spec version so downstream consumers detect the break.
Was this helpful? React with 👍 or 👎 to provide feedback.
|
I can't run this ultrareview because your workspace has reached its monthly review limit. cubic has reviewed 100,145 of the 100,000 allowed lines of code this month. Reviews resume on 4 September 2026 (in 25 days). Enable flex capacity to cover overages automatically and resume reviews now. Learn how flex capacity works. To help optimise your usage, you can tune cubic to get the most out of your usage limits:
|
Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>
Code Review by Qodo
1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| required: [text] | ||
| properties: | ||
| voiceId: | ||
| type: string | ||
| text: | ||
| type: string |
There was a problem hiding this comment.
1. openapi.yaml exceeds 500 lines 📘 Rule violation ⚙ Maintainability
openapi.yaml is a touched file and is well over the 500-line limit (it contains content past line 2400). This makes the spec harder to maintain and violates the maximum file-length requirement.
Agent Prompt
## Issue description
The PR modifies `openapi.yaml`, which is far larger than the 500-line maximum required by the compliance checklist.
## Issue Context
The file contains content beyond line 2400, indicating it significantly exceeds the 500-line cap.
## Fix Focus Areas
- openapi.yaml[393-410]
- openapi.yaml[2241-2251]
- openapi.yaml[2404-2411]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
There was a problem hiding this comment.
openapi.yaml is a long-standing monolithic spec (2400+ lines before this PR); splitting it to meet the 500-line rule is a large restructuring outside the scope of this contract-alignment PR.
Qodo FixerNo findings are within the configured fix scope. To change which findings are fixed, adjust the setting on your Qodo configuration page. |
Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>
🟢 WAVE BugBot — clearNo confident findings on the changed lines. Local review · $0 inference · wave-dispatch |
1 participant
The api-spec was out of sync with the live gateway (verified today by probing api.wave.online):
ClipCreatepreviously required the rejected numericvideoId/startTime/endTimeshape. The gateway accepts{ source: "<recording-id>", in: "5s", out: "10s" }.POST /voice(not/voice/generate), requiring onlytext(voiceIdoptional, also sent asvoice_id). The primary 200 returns rawaudio/mpegbytes.CHANGELOG updated.
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is enabled.Note
Align Clip and Voice API contracts with live gateway
POST /voice/generatetoPOST /voice; the 200 response now returns rawaudio/mpegbytes by default, with JSON only when opting into timestamps or async engines.ClipCreatenow requiressource,in, andout(relative time strings e.g.5s,2m30s) instead ofvideoId,startTime, andendTime(numeric).VoiceGenerateRequestnow only requirestext;voiceIdandvoice_idare optional snake/camel aliases but mutually exclusive — providing both is invalid./voice/generate, numeric clip times, or passingvoiceIdas required must update.Macroscope summarized 16af177.