{ "openapi": "3.1.0", "info": { "title": "ReelWords Caption API", "version": "1.0.0", "description": "ReelWords REST API for creating caption jobs, polling status, and downloading rendered videos." }, "servers": [ { "url": "https://api.reelwords.ai" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v1/caption-jobs": { "post": { "summary": "Create a caption job", "description": "Creates a new caption render job. The style ID is required and must match a known style preset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionJobRequest" }, "examples": { "basic": { "value": { "videoUrl": "https://cdn.reelwords.ai/sample.mp4", "preferences": { "addEmojis": true, "maxWordsPerLine": 6, "style": { "styleId": "style1", "positionY": 82, "fontSize": 54, "highlightColor": "#FFD803", "hookColor": "#FF5CAA" } } } } } } } }, "responses": { "201": { "description": "Caption job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionJob" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Usage limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Style not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/caption-jobs/{id}": { "get": { "summary": "Fetch caption job status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Caption job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionJob" } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/caption-jobs/{id}/retry": { "post": { "summary": "Retry a failed caption job", "description": "Restarts a failed caption job without consuming an additional credit.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Caption job restarted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionJob" } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Job is not in a failed state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/caption-jobs/{id}/video": { "get": { "summary": "Download rendered video", "description": "Redirects to a signed storage URL once the job completes.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "Redirect to signed video URL", "headers": { "Location": { "description": "Signed download URL", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Job not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotReadyError" } } } } } } }, "/api/v1/transcript-jobs": { "post": { "summary": "Create a transcript job", "description": "Creates a new transcript extraction job from a public video URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJobRequest" }, "examples": { "basic": { "value": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "language": "en" } } } } } }, "responses": { "201": { "description": "Transcript job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJob" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Usage limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/transcript-jobs/usage": { "get": { "summary": "Get transcript usage", "description": "Returns current rolling-week transcript usage, limit, and remaining credits.", "responses": { "200": { "description": "Usage payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptUsage" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/transcript-jobs/{id}": { "get": { "summary": "Fetch transcript job status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transcript job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJob" } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/transcript-jobs/{id}/download": { "get": { "summary": "Download transcript output", "description": "Downloads transcript in one of: srt, vtt, txt, txt_timestamps.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "srt", "vtt", "txt", "txt_timestamps" ] } } ], "responses": { "200": { "description": "Transcript file payload", "content": { "application/x-subrip": { "schema": { "type": "string" } }, "text/vtt": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid format or job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API key required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Job not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotReadyError" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key starting with rw_." } }, "schemas": { "CaptionJobRequest": { "type": "object", "required": [ "videoUrl", "preferences" ], "properties": { "videoUrl": { "type": "string", "format": "uri" }, "preferences": { "$ref": "#/components/schemas/CaptionPreferences" } } }, "CaptionPreferences": { "type": "object", "required": [ "style" ], "properties": { "addEmojis": { "type": "boolean" }, "maxWordsPerLine": { "type": "integer", "minimum": 1 }, "style": { "$ref": "#/components/schemas/CaptionStyle" } } }, "CaptionStyle": { "type": "object", "required": [ "styleId" ], "properties": { "styleId": { "type": "string" }, "positionY": { "type": "number" }, "fontSize": { "type": "number" }, "mainColor": { "type": "string" }, "highlightColor": { "type": "string" }, "hookColor": { "type": "string" }, "highlightOpacity": { "type": "number", "minimum": 0, "maximum": 1 }, "highlightCornerRadius": { "type": "number" }, "highlightMode": { "type": "string", "enum": [ "text", "block", "scale" ] }, "highlightScale": { "type": "number" }, "fontFamily": { "type": "string" }, "styleClasses": { "type": "string" } } }, "CaptionJob": { "type": "object", "required": [ "id", "status", "createdAt", "sourceVideoUrl", "preferences" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "failureReason": { "type": [ "string", "null" ] }, "failureMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cleanupAfter": { "type": [ "string", "null" ], "format": "date-time" }, "sourceVideoUrl": { "type": "string", "format": "uri" }, "preferences": { "$ref": "#/components/schemas/CaptionPreferences" }, "metadata": { "$ref": "#/components/schemas/CaptionJobMetadata" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/CaptionJobResult" }, { "type": "null" } ] } } }, "CaptionJobMetadata": { "type": "object", "properties": { "videoWidth": { "type": "integer" }, "videoHeight": { "type": "integer" }, "captionCount": { "type": "integer" } }, "additionalProperties": true }, "CaptionJobResult": { "type": "object", "properties": { "downloadUrl": { "type": "string", "format": "uri" }, "storagePath": { "type": "string" }, "downloadEndpoint": { "type": "string" } } }, "TranscriptJobRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "language": { "type": "string", "description": "Optional BCP-47 language hint (for example: en, es, fr)." } } }, "TranscriptSegment": { "type": "object", "required": [ "start", "end", "text" ], "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } } }, "TranscriptFormat": { "type": "object", "required": [ "id", "label", "extension", "downloadEndpoint" ], "properties": { "id": { "type": "string", "enum": [ "srt", "vtt", "txt", "txt_timestamps" ] }, "label": { "type": "string" }, "extension": { "type": "string" }, "downloadEndpoint": { "type": "string" } } }, "TranscriptJobResult": { "type": "object", "required": [ "segments", "preview", "formats" ], "properties": { "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptSegment" } }, "preview": { "type": "string" }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptFormat" } } } }, "TranscriptJob": { "type": "object", "required": [ "id", "status", "createdAt", "updatedAt", "sourceUrl", "segmentCount", "result" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "started", "processing", "complete", "failed" ] }, "failureReason": { "type": [ "string", "null" ] }, "failureMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sourceUrl": { "type": "string", "format": "uri" }, "title": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "transcriptSource": { "type": [ "string", "null" ], "enum": [ "native_captions", "gemini_asr", null ] }, "language": { "type": [ "string", "null" ] }, "segmentCount": { "type": "integer" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/TranscriptJobResult" }, { "type": "null" } ] } } }, "TranscriptUsage": { "type": "object", "required": [ "used", "limit", "remaining", "creditBalance", "planTier" ], "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "creditBalance": { "type": "integer" }, "planTier": { "type": "string", "enum": [ "free", "pro" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "additionalProperties": true }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "details": { "type": "object" } } } ] }, "NotReadyError": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } ] } } } }