feat: content V2 docs — malleable-first architecture, templates optional#100
Open
sidneyswift wants to merge 1 commit intomainfrom
Open
feat: content V2 docs — malleable-first architecture, templates optional#100sidneyswift wants to merge 1 commit intomainfrom
sidneyswift wants to merge 1 commit intomainfrom
Conversation
- OpenAPI: move PATCH edit from /video to /content, add image_url input
- OpenAPI: ContentTemplate schema — rename name→id, drop defaultLipsync
- OpenAPI: add GET /api/content/templates/{id} detail endpoint
- OpenAPI: add template field to video, image, text primitive schemas
- OpenAPI: make pipeline template optional (remove default)
- OpenAPI: remove V1 artifacts (era_config, pipeline_config)
- Guide: new content.mdx — primitives, templates, override priority, video modes
- Guide: update content-agent.mdx — template is optional
- Nav: add Content group to Guides tab
Made-with: Cursor
📝 WalkthroughWalkthroughThe pull request updates API documentation and OpenAPI specifications to introduce new content primitive endpoints ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
api-reference/openapi.json (2)
5999-6049:⚠️ Potential issue | 🔴 CriticalAdd missing schema definitions for the
/api/music/*endpointsThe operations reference schemas
MusicComposeRequest,MusicComposeDetailedRequest,MusicStreamRequest,MusicCreatePlanRequest,MusicCreatePlanResponse, andMusicErrorResponse, but none are defined incomponents.schemas. This breaks any OpenAPI resolver or codegen tool. Add these schema definitions tocomponents.schemasor update the$refs to point to existing definitions.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5999 - 6049, The OpenAPI spec references missing schema definitions: MusicComposeRequest, MusicComposeDetailedRequest, MusicStreamRequest, MusicCreatePlanRequest, MusicCreatePlanResponse, and MusicErrorResponse; add these schemas under components.schemas (or change the $ref targets to the correct existing schema names) so the $ref entries in the endpoints resolve; ensure each schema matches the expected request/response shapes (e.g., MusicComposeRequest, MusicComposeDetailedRequest, MusicStreamRequest for request bodies and MusicCreatePlanResponse, MusicErrorResponse for responses) and update any example/required fields accordingly.
13660-13775:⚠️ Potential issue | 🟠 MajorEncode the input and config requirements as JSON Schema constraints.
The schema currently has no machine-readable enforcement for its documented rules. An empty object
{}would pass validation despite requiring at least one ofvideo_url,image_url, oraudio_url, and eithertemplateoroperations. This weakens validation, SDK generation, and documentation.Use
anyOfto enforce at least one input, andallOfwithanyOfto enforce the template/operations requirement. Also addminItems: 1to theoperationsarray.🔧 Suggested fix
"ContentCreateEditRequest": { "type": "object", "description": "Must provide at least one input (video_url, image_url, or audio_url)", + "anyOf": [ + { "required": ["video_url"] }, + { "required": ["image_url"] }, + { "required": ["audio_url"] } + ], + "allOf": [ + { + "anyOf": [ + { "required": ["template"] }, + { "required": ["operations"] } + ] + } + ], "properties": { @@ "operations": { "type": "array", + "minItems": 1, "description": "Array of edit operations to apply in order. Required if template is not provided.",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 13660 - 13775, The ContentCreateEditRequest schema currently allows an empty object; update the JSON Schema for ContentCreateEditRequest to enforce the documented rules by adding an anyOf at the root that requires at least one of the input URLs (video_url, image_url, audio_url), add an allOf group that enforces "template OR operations" (use anyOf inside allOf: one branch requires "template", the other requires "operations"), and add "minItems: 1" to the operations array definition; ensure these constraints reference the existing property names (video_url, image_url, audio_url, template, operations) so validators and generated SDKs will reject invalid empty payloads.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 12307-12310: Update the OpenAPI schema for ContentCreateResponse
so the template property is not required and its schema allows null;
specifically, remove "template" from the ContentCreateResponse's required array
and change the template schema (under the ContentCreateResponse object) to
accept type "string" or "null" (or add "nullable": true) so successful
template-free (malleable) responses can be represented. Apply the same change
for the duplicate/related response definitions referenced around the other block
(the section spanning 12369-12406) to ensure consistency.
- Around line 12505-12630: The ContentTemplateDetail.edit.operations schema
currently only exposes the operation "type" and is lossy; update
ContentTemplateDetail.edit.operations to mirror the full operation shape used by
ContentCreateEditRequest.operations by adding the additional properties (e.g.,
start, duration, aspect, content, audio_url, color, font, height, width,
position, stroke_color, replace, max_font_size) with appropriate types and
descriptions and include any relevant required fields so consumers of GET
/api/content/templates/{id} can fully reconstruct the edit pipeline; ensure the
property names exactly match those in ContentCreateEditRequest.operations to
keep schemas consistent.
---
Outside diff comments:
In `@api-reference/openapi.json`:
- Around line 5999-6049: The OpenAPI spec references missing schema definitions:
MusicComposeRequest, MusicComposeDetailedRequest, MusicStreamRequest,
MusicCreatePlanRequest, MusicCreatePlanResponse, and MusicErrorResponse; add
these schemas under components.schemas (or change the $ref targets to the
correct existing schema names) so the $ref entries in the endpoints resolve;
ensure each schema matches the expected request/response shapes (e.g.,
MusicComposeRequest, MusicComposeDetailedRequest, MusicStreamRequest for request
bodies and MusicCreatePlanResponse, MusicErrorResponse for responses) and update
any example/required fields accordingly.
- Around line 13660-13775: The ContentCreateEditRequest schema currently allows
an empty object; update the JSON Schema for ContentCreateEditRequest to enforce
the documented rules by adding an anyOf at the root that requires at least one
of the input URLs (video_url, image_url, audio_url), add an allOf group that
enforces "template OR operations" (use anyOf inside allOf: one branch requires
"template", the other requires "operations"), and add "minItems: 1" to the
operations array definition; ensure these constraints reference the existing
property names (video_url, image_url, audio_url, template, operations) so
validators and generated SDKs will reject invalid empty payloads.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 73f89d3e-16ff-4e4a-ab48-a179bf5710b3
📒 Files selected for processing (6)
api-reference/content/edit.mdxapi-reference/content/template-detail.mdxapi-reference/openapi.jsoncontent-agent.mdxcontent.mdxdocs.json
Comment on lines
12307
to
+12310
| "template": { | ||
| "type": "string", | ||
| "description": "The template to use for content generation. Defines the visual style, scene, and prompt configuration. If omitted, defaults to `artist-caption-bedroom`. See [GET /api/content/templates](/api-reference/content/templates) for available options.", | ||
| "example": "artist-caption-stage", | ||
| "default": "artist-caption-bedroom" | ||
| "description": "Optional template ID for content generation. Defines the visual style, scene, and prompt configuration. When omitted, the pipeline runs in malleable mode using only the params you provide. See GET /api/content/templates for available options.", | ||
| "example": "artist-caption-stage" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("api-reference/openapi.json").read_text())
req = data["components"]["schemas"]["ContentCreateRequest"]
resp = data["components"]["schemas"]["ContentCreateResponse"]
print("ContentCreateRequest.required:", req.get("required", []))
print("ContentCreateResponse.required:", resp.get("required", []))
print("ContentCreateResponse.template:", resp["properties"]["template"])
PYRepository: recoupable/docs
Length of output: 327
Fix the create-response contract to support template-free requests.
The request documentation correctly shows template as optional and allows malleable mode operation without a template. However, ContentCreateResponse still requires a non-null template field, making it impossible to represent successful template-less calls with the published schema.
Remove template from the response's required fields and allow null values:
🔧 Suggested fix
"ContentCreateResponse": {
"type": "object",
"required": [
"runIds",
"status",
- "artist_account_id",
- "template"
+ "artist_account_id"
],
@@
"template": {
- "type": "string",
- "description": "The template being used",
- "example": "artist-caption-bedroom"
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Template ID when a preset pipeline is used; null in malleable mode.",
+ "example": null
},Also applies to: 12369-12406
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 12307 - 12310, Update the OpenAPI
schema for ContentCreateResponse so the template property is not required and
its schema allows null; specifically, remove "template" from the
ContentCreateResponse's required array and change the template schema (under the
ContentCreateResponse object) to accept type "string" or "null" (or add
"nullable": true) so successful template-free (malleable) responses can be
represented. Apply the same change for the duplicate/related response
definitions referenced around the other block (the section spanning 12369-12406)
to ensure consistency.
Comment on lines
+12505
to
12630
| "ContentTemplateDetail": { | ||
| "type": "object", | ||
| "required": [ | ||
| "id", | ||
| "description" | ||
| ], | ||
| "description": "Full configuration for a content creation template including image prompts, video motion config, caption style rules, and edit operations.", | ||
| "properties": { | ||
| "id": { | ||
| "type": "string", | ||
| "description": "Template identifier", | ||
| "example": "artist-caption-bedroom" | ||
| }, | ||
| "defaultLipsync": { | ||
| "type": "boolean", | ||
| "description": "Whether this template defaults to lip-sync mode when the `lipsync` flag is not explicitly set", | ||
| "example": false | ||
| "description": { | ||
| "type": "string", | ||
| "description": "Human-readable description of the template", | ||
| "example": "Moody bedroom selfie. Artist on camera with deadpan expression, purple LED lighting, dark room." | ||
| }, | ||
| "image": { | ||
| "type": "object", | ||
| "description": "Image generation configuration", | ||
| "properties": { | ||
| "prompt": { | ||
| "type": "string", | ||
| "description": "Default image prompt used when no caller prompt is provided" | ||
| }, | ||
| "reference_images": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string", | ||
| "format": "uri" | ||
| }, | ||
| "description": "Reference image URLs for style conditioning" | ||
| }, | ||
| "style_rules": { | ||
| "type": "object", | ||
| "description": "Style constraints (lighting, colors, composition)" | ||
| } | ||
| } | ||
| }, | ||
| "video": { | ||
| "type": "object", | ||
| "description": "Video generation configuration", | ||
| "properties": { | ||
| "moods": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "description": "Mood descriptors for motion prompt generation" | ||
| }, | ||
| "movements": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "description": "Camera/subject movement descriptors" | ||
| } | ||
| } | ||
| }, | ||
| "caption": { | ||
| "type": "object", | ||
| "description": "Caption generation configuration", | ||
| "properties": { | ||
| "guide": { | ||
| "type": "object", | ||
| "description": "Caption style guide", | ||
| "properties": { | ||
| "tone": { | ||
| "type": "string", | ||
| "description": "Voice and tone direction" | ||
| }, | ||
| "rules": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "description": "Style rules for caption generation" | ||
| }, | ||
| "formats": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "description": "Allowed caption formats" | ||
| } | ||
| } | ||
| }, | ||
| "examples": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "description": "Example captions for few-shot prompting" | ||
| } | ||
| } | ||
| }, | ||
| "edit": { | ||
| "type": "object", | ||
| "description": "Post-processing edit operations", | ||
| "properties": { | ||
| "operations": { | ||
| "type": "array", | ||
| "description": "Default edit operations applied during post-processing", | ||
| "items": { | ||
| "type": "object", | ||
| "required": [ | ||
| "type" | ||
| ], | ||
| "properties": { | ||
| "type": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "trim", | ||
| "crop", | ||
| "resize", | ||
| "overlay_text", | ||
| "mux_audio" | ||
| ], | ||
| "description": "Operation type" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
python - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("api-reference/openapi.json").read_text())
detail_props = data["components"]["schemas"]["ContentTemplateDetail"]["properties"]["edit"]["properties"]["operations"]["items"]["properties"]
edit_props = data["components"]["schemas"]["ContentCreateEditRequest"]["properties"]["operations"]["items"]["properties"]
print("ContentTemplateDetail.edit.operations fields:", sorted(detail_props.keys()))
print("ContentCreateEditRequest.operations fields:", sorted(edit_props.keys()))
PYRepository: recoupable/docs
Length of output: 313
🏁 Script executed:
#!/bin/bash
# Check what schemas are at lines 13683-13763
sed -n '13683,13763p' api-reference/openapi.json | head -50Repository: recoupable/docs
Length of output: 1802
ContentTemplateDetail.edit.operations is too lossy for a detail endpoint.
The schema only exposes type, while ContentCreateEditRequest.operations supports the full operation parameters (start, duration, aspect, content, audio_url, color, font, height, width, position, stroke_color, replace, max_font_size). Consumers calling GET /api/content/templates/{id} cannot reconstruct the advertised edit pipeline with just the operation type. Include all supported operation properties in the detail schema.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 12505 - 12630, The
ContentTemplateDetail.edit.operations schema currently only exposes the
operation "type" and is lossy; update ContentTemplateDetail.edit.operations to
mirror the full operation shape used by ContentCreateEditRequest.operations by
adding the additional properties (e.g., start, duration, aspect, content,
audio_url, color, font, height, width, position, stroke_color, replace,
max_font_size) with appropriate types and descriptions and include any relevant
required fields so consumers of GET /api/content/templates/{id} can fully
reconstruct the edit pipeline; ensure the property names exactly match those in
ContentCreateEditRequest.operations to keep schemas consistent.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/videoto/content, renamed ContentTemplatename→id, droppeddefaultLipsync, added template field to video/image/text schemas, addedGET /api/content/templates/{id}detail endpoint, made pipeline template optional, removed V1 artifactscontent.mdx— malleable-first philosophy, primitives table, curl examples, architecture diagram, video modes, iteration guidanceTest plan
npx mintlify@latest devMade with Cursor
Summary by CodeRabbit
New Features
Documentation