Skip to content

Commit 2ccfba1

Browse files
sweetmantechclaude
sweetmantech
and
claude
authored
docs: align OpenAPI spec with content API implementation (#120)
* docs: align content OpenAPI spec with API implementation Applied to the split content.json (after #121 merged): 1. Image: add num_images, aspect_ratio, resolution; fix model name; add images array 2. Video: make image_url required; document model limitation 3. Edit: remove image_url (not implemented) 4. Transcribe: rename songUrl → audioUrl 5. Upscale: add upscale_factor and target_resolution Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: align edit endpoint description with schema (remove image reference) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add missing video mode response, transcribe params, fix caption examples 1. Video response: add mode field (prompt/animate/reference/extend/first-last/lipsync) 2. Transcribe request: add language, chunk_level, diarize params 3. Caption response: fix color examples to match API (white/black, maxFontSize 42) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 0c38bd7 commit 2ccfba1

File tree

1 file changed

+94
-18
lines changed

1 file changed

+94
-18
lines changed

‎api-reference/openapi/content.json‎

Lines changed: 94 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -549,7 +549,7 @@
549549
},
550550
"/api/content": {
551551
"patch": {
552-
"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.",
552+
"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.",
553553
"security": [
554554
{
555555
"apiKeyAuth": []
@@ -2103,6 +2103,26 @@
21032103
"minItems": 1,
21042104
"description": "Audio file URLs to transcribe"
21052105
},
2106+
"language": {
2107+
"type": "string",
2108+
"default": "en",
2109+
"description": "Language code for transcription (e.g. en, es, fr). Defaults to en."
2110+
},
2111+
"chunk_level": {
2112+
"type": "string",
2113+
"enum": [
2114+
"none",
2115+
"segment",
2116+
"word"
2117+
],
2118+
"default": "word",
2119+
"description": "Granularity of timestamp chunks. Defaults to word-level."
2120+
},
2121+
"diarize": {
2122+
"type": "boolean",
2123+
"default": false,
2124+
"description": "Enable speaker diarization. Defaults to false."
2125+
},
21062126
"model": {
21072127
"type": "string",
21082128
"description": "fal.ai model ID. Defaults to fal-ai/whisper"
@@ -2112,15 +2132,15 @@
21122132
"ContentCreateAudioResponse": {
21132133
"type": "object",
21142134
"required": [
2115-
"songUrl",
2135+
"audioUrl",
21162136
"fullLyrics",
21172137
"segments",
21182138
"segmentCount"
21192139
],
21202140
"properties": {
2121-
"songUrl": {
2141+
"audioUrl": {
21222142
"type": "string",
2123-
"description": "URL of the transcribed song"
2143+
"description": "URL of the transcribed audio"
21242144
},
21252145
"fullLyrics": {
21262146
"type": "string",
@@ -2163,18 +2183,13 @@
21632183
},
21642184
"ContentCreateEditRequest": {
21652185
"type": "object",
2166-
"description": "Must provide at least one input (video_url, image_url, or audio_url)",
2186+
"description": "Must provide at least one input (video_url or audio_url)",
21672187
"properties": {
21682188
"video_url": {
21692189
"type": "string",
21702190
"format": "uri",
21712191
"description": "Input video URL"
21722192
},
2173-
"image_url": {
2174-
"type": "string",
2175-
"format": "uri",
2176-
"description": "Input image URL"
2177-
},
21782193
"audio_url": {
21792194
"type": "string",
21802195
"format": "uri",
@@ -2359,22 +2374,50 @@
23592374
},
23602375
"description": "Optional reference image URLs to guide generation"
23612376
},
2377+
"num_images": {
2378+
"type": "integer",
2379+
"minimum": 1,
2380+
"maximum": 4,
2381+
"default": 1,
2382+
"description": "Number of images to generate (1-4)"
2383+
},
2384+
"aspect_ratio": {
2385+
"type": "string",
2386+
"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"],
2387+
"default": "auto",
2388+
"description": "Aspect ratio of the generated image"
2389+
},
2390+
"resolution": {
2391+
"type": "string",
2392+
"enum": ["0.5K", "1K", "2K", "4K"],
2393+
"default": "1K",
2394+
"description": "Output resolution"
2395+
},
23622396
"model": {
23632397
"type": "string",
2364-
"description": "fal.ai model ID. Defaults to fal-ai/nano-banana-pro/edit"
2398+
"description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2"
23652399
}
23662400
}
23672401
},
23682402
"ContentCreateImageResponse": {
23692403
"type": "object",
23702404
"required": [
2371-
"imageUrl"
2405+
"imageUrl",
2406+
"images"
23722407
],
23732408
"properties": {
23742409
"imageUrl": {
23752410
"type": "string",
23762411
"format": "uri",
2377-
"description": "URL of the generated image"
2412+
"description": "URL of the first generated image"
2413+
},
2414+
"images": {
2415+
"type": "array",
2416+
"items": {
2417+
"type": "string",
2418+
"format": "uri"
2419+
},
2420+
"description": "URLs of all generated images. Contains one element when num_images is 1."
23782421
}
23792422
}
23802423
},
@@ -2551,17 +2594,17 @@
25512594
"color": {
25522595
"type": "string",
25532596
"description": "Text color as a CSS color value",
2554-
"example": "#FFFFFF"
2597+
"example": "white"
25552598
},
25562599
"borderColor": {
25572600
"type": "string",
25582601
"description": "Text border/stroke color as a CSS color value",
2559-
"example": "#000000"
2602+
"example": "black"
25602603
},
25612604
"maxFontSize": {
25622605
"type": "number",
25632606
"description": "Maximum font size in pixels",
2564-
"example": 48
2607+
"example": 42
25652608
}
25662609
}
25672610
},
@@ -2584,6 +2627,23 @@
25842627
"video"
25852628
],
25862629
"description": "Whether the input is an image or video"
2630+
},
2631+
"upscale_factor": {
2632+
"type": "number",
2633+
"minimum": 1,
2634+
"maximum": 4,
2635+
"default": 2,
2636+
"description": "Upscale multiplier (1-4x). Defaults to 2x."
2637+
},
2638+
"target_resolution": {
2639+
"type": "string",
2640+
"enum": [
2641+
"720p",
2642+
"1080p",
2643+
"1440p",
2644+
"2160p"
2645+
],
2646+
"description": "Target output resolution. When provided, overrides upscale_factor with a resolution-based upscale."
25872647
}
25882648
}
25892649
},
@@ -2602,6 +2662,9 @@
26022662
},
26032663
"ContentCreateVideoRequest": {
26042664
"type": "object",
2665+
"required": [
2666+
"image_url"
2667+
],
26052668
"properties": {
26062669
"template": {
26072670
"type": "string",
@@ -2626,7 +2689,7 @@
26262689
"image_url": {
26272690
"type": "string",
26282691
"format": "uri",
2629-
"description": "Image URL. Used as the first frame (animate), style reference (reference), start frame (first-last), or face source (lipsync)"
2692+
"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."
26302693
},
26312694
"end_image_url": {
26322695
"type": "string",
@@ -2692,13 +2755,26 @@
26922755
"ContentCreateVideoResponse": {
26932756
"type": "object",
26942757
"required": [
2695-
"videoUrl"
2758+
"videoUrl",
2759+
"mode"
26962760
],
26972761
"properties": {
26982762
"videoUrl": {
26992763
"type": "string",
27002764
"format": "uri",
27012765
"description": "URL of the generated video"
2766+
},
2767+
"mode": {
2768+
"type": "string",
2769+
"enum": [
2770+
"prompt",
2771+
"animate",
2772+
"reference",
2773+
"extend",
2774+
"first-last",
2775+
"lipsync"
2776+
],
2777+
"description": "The resolved video generation mode (explicit or inferred from inputs)"
27022778
}
27032779
}
27042780
},

0 commit comments

Comments
 (0)