{"openapi":"3.0.0","info":{"title":"VeoAPI - Video Generation API","description":"REST API for video generation using Google Veo AI models","version":"1.0.0","contact":{"name":"VeoAPI Support","url":"https://veoapi.site"}},"servers":[{"url":"https://veoapi.org","description":"VeoAPI Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API token for authorization. Can be obtained in dashboard under 'API Tokens' section"}},"schemas":{"VideoGeneration":{"type":"object","properties":{"videoId":{"type":"string","description":"Unique video identifier","example":"efc0b62e-a9c4-4355-a946-151ec91d45a5"},"status":{"type":"string","enum":["generating","processing","completed","failed"],"description":"Current video generation status"},"prompt":{"type":"string","description":"Text description for video generation","example":"A beautiful sunset over mountains with birds flying in the distance"},"model":{"type":"string","enum":["veo31_fast","veo31_pro","veo3_fast","veo3_pro","veo3_quality"],"description":"Model used for video generation (Veo 3.1 models). Legacy veo3_* aliases accepted."},"cost":{"type":"number","description":"Generation cost in credits","example":100},"progress":{"type":"number","minimum":0,"maximum":100,"description":"Generation progress percentage"},"seed":{"type":"number","description":"Seed for reproducible results","example":12345},"language":{"type":"string","enum":["en"],"description":"Language used for video generation","example":"en"},"createdAt":{"type":"string","format":"date-time","description":"Video creation timestamp in ISO 8601 format"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp in ISO 8601 format"},"completedAt":{"type":"string","format":"date-time","description":"Video completion timestamp in ISO 8601 format (if applicable)"},"downloadUrl":{"type":"string","description":"Video download URL (available when status is 'completed')","example":"/api/videos/efc0b62e-a9c4-4355-a946-151ec91d45a5/download"}},"required":["videoId","status","prompt","model","cost","progress","createdAt"]},"VideoGenerationRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"Text description for video generation","example":"A beautiful sunset over mountains with birds flying in the distance"},"model":{"type":"string","enum":["veo31_fast","veo31_pro","veo3_fast","veo3_pro","veo3_quality"],"description":"Model for video generation (Veo 3.1 models). Legacy veo3_* aliases accepted."},"orientation":{"type":"string","enum":["landscape","portrait"],"default":"landscape","description":"Video orientation: landscape (16:9) or portrait (9:16)"},"image":{"type":"string","description":"Start image for image-to-video generation (base64 encoded with data:image/jpeg;base64, prefix).","example":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."},"endImage":{"type":"string","description":"End image for dual mode (supported by veo31_fast and veo31_pro)"},"referenceImages":{"type":"array","items":{"type":"string"},"description":"Reference images array (supported only by veo31_fast in landscape orientation; not supported for veo31_pro)"},"continuation_video_id":{"type":"string","description":"ID of original video to continue"},"skipContinuationImage":{"type":"boolean","description":"Continue by prompt only without last frame extraction"},"seed":{"type":"number","description":"Seed for reproducible results","example":12345},"language":{"type":"string","enum":["en"],"default":"en","description":"Language for video generation and response messages"}},"required":["prompt"]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Response data"},"message":{"type":"string","description":"Additional message"}},"required":["success","data"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error description"}},"required":["code","message"]}},"required":["success","error"]},"VideoList":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/VideoGeneration"}},"total":{"type":"number","description":"Total number of videos"},"limit":{"type":"number","description":"Video limit in response"},"offset":{"type":"number","description":"Offset for pagination"}},"required":["videos","total","limit","offset"]}}},"paths":{"/api/v1/videos/generate":{"post":{"tags":["Video Generation"],"summary":"Generate new video","description":"Creates a new video from text description or image. Asynchronous operation - returns immediately with 'generating' status.","operationId":"generateVideo","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationRequest"},"examples":{"textOnly":{"summary":"Text-only generation","value":{"prompt":"A beautiful sunset over mountains with birds flying in the distance","model":"veo31_fast","orientation":"landscape","seed":12345,"language":"en"}},"withImage":{"summary":"Image-to-video generation","value":{"prompt":"Transform this image into a video with gentle movement","model":"veo31_fast","orientation":"portrait","image":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...","seed":12345,"language":"en"}}}}}},"responses":{"200":{"description":"Video queued for generation","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/VideoGeneration"},{"type":"object","properties":{"creditsUsed":{"type":"number","description":"Credits spent on generation"},"remainingCredits":{"type":"number","description":"Remaining credits"}}}]},"message":{"type":"string","example":"Video queued for generation"}}}]},"example":{"success":true,"data":{"videoId":"efc0b62e-a9c4-4355-a946-151ec91d45a5","status":"generating","prompt":"A beautiful sunset over mountains with birds flying in the distance","model":"veo31_fast","seed":12345,"language":"en","cost":200,"progress":0,"creditsUsed":200,"remainingCredits":4800,"createdAt":"2025-01-15T10:30:15.123Z"},"message":"Video queued for generation"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingPrompt":{"summary":"Missing prompt","value":{"success":false,"error":{"code":"MISSING_PROMPT","message":"Prompt is required."}}},"invalidModel":{"summary":"Invalid model","value":{"success":false,"error":{"code":"INVALID_MODEL","message":"Invalid model. Supported models: veo31_fast, veo31_pro"}}}}}}},"401":{"description":"Authorization error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid or inactive API token."}}}}},"500":{"description":"Internal server error. IMPORTANT: Video may be created asynchronously in background even with HTTP error. Check video list after 30-60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/videos/{video_id}":{"get":{"tags":["Video Retrieval"],"summary":"Get video status and data","description":"Returns video information including generation status, progress and download link (if ready).","operationId":"getVideo","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"description":"Unique video identifier","schema":{"type":"string","example":"efc0b62e-a9c4-4355-a946-151ec91d45a5"}},{"name":"language","in":"query","required":false,"description":"Language for response messages","schema":{"type":"string","enum":["en"],"default":"en"}}],"responses":{"200":{"description":"Video information","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoGeneration"}}}]},"examples":{"completed":{"summary":"Completed video","value":{"success":true,"data":{"videoId":"efc0b62e-a9c4-4355-a946-151ec91d45a5","status":"completed","prompt":"A beautiful sunset over mountains","model":"veo31_fast","cost":100,"progress":100,"seed":12345,"language":"en","createdAt":"2025-01-15T10:30:15.123Z","updatedAt":"2025-01-15T10:35:22.456Z","completedAt":"2025-01-15T10:35:22.456Z","downloadUrl":"/api/videos/efc0b62e-a9c4-4355-a946-151ec91d45a5/download"}}},"processing":{"summary":"Video in progress","value":{"success":true,"data":{"videoId":"efc0b62e-a9c4-4355-a946-151ec91d45a5","status":"generating","prompt":"A beautiful sunset over mountains","model":"veo31_fast","cost":100,"progress":45,"seed":12345,"language":"en","createdAt":"2025-01-15T10:30:15.123Z","updatedAt":"2025-01-15T10:33:45.789Z"}}}}}}},"401":{"description":"Authorization error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"VIDEO_NOT_FOUND","message":"Video not found"}}}}}}}},"/api/v1/videos":{"get":{"tags":["Video List"],"summary":"Get list of all videos","description":"Returns a list of all user's video generations with pagination support.","operationId":"listVideos","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of videos in response (maximum: 100)","schema":{"type":"number","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of videos to skip (for pagination)","schema":{"type":"number","minimum":0,"default":0}},{"name":"language","in":"query","required":false,"description":"Language for response messages","schema":{"type":"string","enum":["en"],"default":"en"}}],"responses":{"200":{"description":"Video list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoList"}}}]},"example":{"success":true,"data":{"videos":[{"videoId":"efc0b62e-a9c4-4355-a946-151ec91d45a5","status":"completed","prompt":"A beautiful sunset over mountains","model":"veo31_fast","cost":100,"progress":100,"seed":12345,"language":"en","createdAt":"2025-01-15T10:30:15.123Z","updatedAt":"2025-01-15T10:35:22.456Z","completedAt":"2025-01-15T10:35:22.456Z","downloadUrl":"/api/videos/efc0b62e-a9c4-4355-a946-151ec91d45a5/download"},{"videoId":"f7d3c2a1-8b4e-4c5d-9e6f-1a2b3c4d5e6f","status":"processing","prompt":"A majestic eagle soaring through clouds","model":"veo31_fast","cost":200,"progress":67,"seed":67890,"createdAt":"2025-01-15T11:15:30.456Z","updatedAt":"2025-01-15T11:18:45.123Z"}],"total":125,"limit":100,"offset":20}}}}},"401":{"description":"Authorization error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/videos/{video_id}/retry":{"post":{"tags":["Video Generation"],"summary":"Retry video generation","description":"Retries a video generation with all original parameters including images. Asynchronous operation - returns immediately with 'generating' status.","operationId":"retryVideo","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"description":"ID of video to retry","schema":{"type":"string","example":"efc0b62e-a9c4-4355-a946-151ec91d45a5"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["en","ru"],"default":"en","description":"Language for response messages"}}}}}},"responses":{"200":{"description":"Video retry queued","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/VideoGeneration"},{"type":"object","properties":{"creditsUsed":{"type":"number","description":"Credits spent on retry"},"remainingCredits":{"type":"number","description":"Remaining credits"}}}]},"message":{"type":"string","example":"Video generation retry queued"}}}]},"example":{"success":true,"data":{"videoId":"new-video-id-after-retry","status":"generating","prompt":"Original prompt from video","model":"veo31_fast","seed":12345,"language":"en","cost":200,"progress":0,"creditsUsed":200,"remainingCredits":3800,"createdAt":"2025-01-15T11:00:15.123Z"},"message":"Video generation retry queued"}}}},"401":{"description":"Authorization error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/videos/{video_id}/trim":{"post":{"tags":["Video Editing"],"summary":"Trim a completed video","description":"Synchronously trims a completed video from start and/or end. Returns new videoId (type: trimmed).","operationId":"trimVideo","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"description":"Original video ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startOffsetSec":{"type":"number","description":"Trim from start in seconds"},"endOffsetSec":{"type":"number","description":"Trim from end in seconds"},"language":{"type":"string","enum":["en","ru"],"description":"Response language"}}}}}},"responses":{"201":{"description":"Video successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid params"},"404":{"description":"Video not found"},"500":{"description":"Internal error"}}}},"/api/v1/videos/merge":{"post":{"tags":["Video Editing"],"summary":"Merge multiple completed videos","description":"Asynchronously merges 2-10 completed videos into one. Returns 202 and merged videoId.","operationId":"mergeVideos","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string"},"description":"Array of video IDs (2-10)"},"endOffsetSec":{"type":"number","description":"Global end offset for each clip"},"perVideoEndOffsetSec":{"oneOf":[{"type":"array","items":{"type":"number"}},{"type":"object","additionalProperties":{"type":"number"}}]},"language":{"type":"string","enum":["en","ru"],"description":"Response language"}},"required":["videoIds"]}}}},"responses":{"202":{"description":"Merge queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid params"},"404":{"description":"Video not found"},"429":{"description":"Too many requests"},"500":{"description":"Internal error"}}}}},"tags":[{"name":"Video Generation","description":"Operations for creating new videos from text or images"},{"name":"Video Retrieval","description":"Operations for getting video information"},{"name":"Video List","description":"Operations for getting video lists"},{"name":"Quality Enhancement","description":"Operations for enhancing completed video quality"},{"name":"Video Editing","description":"Operations for trimming and merging completed videos"}],"externalDocs":{"description":"Interactive API Documentation","url":"/api-docs"}}