Skip to content

docs: align OpenAPI spec with content API implementation #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 3 commits into from
Apr 9, 2026
Merged

docs: align OpenAPI spec with content API implementation #120

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dafa46e
docs: align content OpenAPI spec with API implementation
sweetmantech Apr 9, 2026
fa24aa2
fix: align edit endpoint description with schema (remove image refere…
sweetmantech Apr 9, 2026
e65c350
docs: add missing video mode response, transcribe params, fix caption…
sweetmantech Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 94 additions & 18 deletions api-reference/openapi/content.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@
},
"/api/content": {
"patch": {
"description": "Apply edits to content — trim, crop, resize, overlay text, or add an audio track. Accepts video, image, or audio input. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.",
"description": "Apply edits to content — trim, crop, resize, overlay text, or add an audio track. Accepts video or audio input. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.",
"security": [
{
"apiKeyAuth": []
Expand Down Expand Up @@ -2103,6 +2103,26 @@
"minItems": 1,
"description": "Audio file URLs to transcribe"
},
"language": {
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

P1: Custom agent: Flag AI Slop and Fabricated Changes

Three new transcribe request parameters (language, chunk_level, diarize) are added but not listed among the PR's verified changes. The PR carefully enumerates all 5 tested discrepancies, and change #4 for transcribe only covers renaming songUrl → audioUrl in the response. Undocumented spec additions in a PR titled "align OpenAPI spec with content API implementation" risk documenting parameters that don't actually exist in the API, misleading consumers.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/content.json, line 2106:

<comment>Three new transcribe request parameters (`language`, `chunk_level`, `diarize`) are added but not listed among the PR's verified changes. The PR carefully enumerates all 5 tested discrepancies, and change #4 for transcribe only covers renaming `songUrl` → `audioUrl` in the response. Undocumented spec additions in a PR titled "align OpenAPI spec with content API implementation" risk documenting parameters that don't actually exist in the API, misleading consumers.</comment>

<file context>
@@ -2103,6 +2103,26 @@
             "minItems": 1,
             "description": "Audio file URLs to transcribe"
           },
+          "language": {
+            "type": "string",
+            "default": "en",
</file context>
Fix with Cubic

"type": "string",
"default": "en",
"description": "Language code for transcription (e.g. en, es, fr). Defaults to en."
},
"chunk_level": {
"type": "string",
"enum": [
"none",
"segment",
"word"
],
"default": "word",
"description": "Granularity of timestamp chunks. Defaults to word-level."
},
"diarize": {
"type": "boolean",
"default": false,
"description": "Enable speaker diarization. Defaults to false."
},
"model": {
"type": "string",
"description": "fal.ai model ID. Defaults to fal-ai/whisper"
Expand All @@ -2112,15 +2132,15 @@
"ContentCreateAudioResponse": {
"type": "object",
"required": [
"songUrl",
"audioUrl",
"fullLyrics",
"segments",
"segmentCount"
],
"properties": {
"songUrl": {
"audioUrl": {
"type": "string",
"description": "URL of the transcribed song"
"description": "URL of the transcribed audio"
},
"fullLyrics": {
"type": "string",
Expand Down Expand Up @@ -2163,18 +2183,13 @@
},
"ContentCreateEditRequest": {
"type": "object",
"description": "Must provide at least one input (video_url, image_url, or audio_url)",
"description": "Must provide at least one input (video_url or audio_url)",
"properties": {
"video_url": {
"type": "string",
"format": "uri",
"description": "Input video URL"
},
"image_url": {
"type": "string",
"format": "uri",
"description": "Input image URL"
},
"audio_url": {
"type": "string",
"format": "uri",
Expand Down Expand Up @@ -2359,22 +2374,50 @@
},
"description": "Optional reference image URLs to guide generation"
},
"num_images": {
"type": "integer",
"minimum": 1,
"maximum": 4,
"default": 1,
"description": "Number of images to generate (1-4)"
},
"aspect_ratio": {
"type": "string",
"enum": ["auto", "21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "4:1", "1:4", "8:1", "1:8"],
"default": "auto",
"description": "Aspect ratio of the generated image"
},
"resolution": {
"type": "string",
"enum": ["0.5K", "1K", "2K", "4K"],
"default": "1K",
"description": "Output resolution"
},
"model": {
"type": "string",
"description": "fal.ai model ID. Defaults to fal-ai/nano-banana-pro/edit"
"description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2"
}
}
},
"ContentCreateImageResponse": {
"type": "object",
"required": [
"imageUrl"
"imageUrl",
"images"
],
"properties": {
"imageUrl": {
"type": "string",
"format": "uri",
"description": "URL of the generated image"
"description": "URL of the first generated image"
},
"images": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "URLs of all generated images. Contains one element when num_images is 1."
}
}
},
Expand Down Expand Up @@ -2551,17 +2594,17 @@
"color": {
"type": "string",
"description": "Text color as a CSS color value",
"example": "#FFFFFF"
"example": "white"
},
"borderColor": {
"type": "string",
"description": "Text border/stroke color as a CSS color value",
"example": "#000000"
"example": "black"
},
"maxFontSize": {
"type": "number",
"description": "Maximum font size in pixels",
"example": 48
"example": 42
}
}
},
Expand All @@ -2584,6 +2627,23 @@
"video"
],
"description": "Whether the input is an image or video"
},
"upscale_factor": {
"type": "number",
"minimum": 1,
"maximum": 4,
"default": 2,
"description": "Upscale multiplier (1-4x). Defaults to 2x."
},
"target_resolution": {
"type": "string",
"enum": [
"720p",
"1080p",
"1440p",
"2160p"
],
"description": "Target output resolution. When provided, overrides upscale_factor with a resolution-based upscale."
}
}
},
Expand All @@ -2602,6 +2662,9 @@
},
"ContentCreateVideoRequest": {
"type": "object",
"required": [
"image_url"
],
"properties": {
"template": {
"type": "string",
Expand All @@ -2626,7 +2689,7 @@
"image_url": {
"type": "string",
"format": "uri",
"description": "Image URL. Used as the first frame (animate), style reference (reference), start frame (first-last), or face source (lipsync)"
"description": "Required. Image URL used as the input frame. The underlying model (fal-ai/veo3.1/fast/image-to-video) requires an image — text-only prompt mode is not supported. Generate an image first via POST /api/content/image if needed."
},
"end_image_url": {
"type": "string",
Expand Down Expand Up @@ -2692,13 +2755,26 @@
"ContentCreateVideoResponse": {
"type": "object",
"required": [
"videoUrl"
"videoUrl",
"mode"
],
"properties": {
"videoUrl": {
"type": "string",
"format": "uri",
"description": "URL of the generated video"
},
"mode": {
"type": "string",
"enum": [
"prompt",
"animate",
"reference",
"extend",
"first-last",
"lipsync"
],
"description": "The resolved video generation mode (explicit or inferred from inputs)"
}
}
},
Expand Down