--- title: "POST /v1/generations" method: POST path: "/v1/generations" tags: ["Generations"] --- # POST /v1/generations `POST /v1/generations` ## Request - Base URL: `https://api.virtuall.pro` - URL: `https://api.virtuall.pro/v1/generations` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` ## Request body - union - LynxTextToModelRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'text_to_model', required - `prompt` string, required - `files` object[] - `id` string, uuid, required - `params` LynxTextToModelParams - `negative_prompt` string - `mesh_detail` 'Low poly' | 'High poly' - `max_polycount` number - `auto_size` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - LynxImageToModelRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'image_to_model', required - `prompt` string - `files` object[], required: Exactly one input image. Role is not used. - `id` string, uuid, required - `params` LynxImageToModelParams - `mesh_detail` 'Low poly' | 'High poly' - `max_polycount` number - `auto_size` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - LynxMultiviewToModelRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'multiview_to_model', required - `prompt` string - `files` object[], required: 1–4 views. `front` is required; roles must be unique across the array. - `id` string, uuid, required - `role` 'front' | 'back' | 'left' | 'right' - `params` LynxMultiviewToModelParams - `mesh_detail` 'Low poly' | 'High poly' - `max_polycount` number - `auto_size` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - LynxModelToTextureRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'model_to_texture', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` LynxModelToTextureParams - `assetId` string, uuid, required - `outputCount` integer - LynxModelToSegmentRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'model_to_segment', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` LynxModelToSegmentParams - `assetId` string, uuid, required - `outputCount` integer - LynxModelToOptimizeMeshRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'model_to_optimize_mesh', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` LynxModelToOptimizeMeshParams - `assetId` string, uuid, required - `outputCount` integer - LynxModelToOptimizeUvRequest: PRECISION · MESH GENERATION & OPTIMIZATION — Advanced 3D mesh generation with detailed geometry and strong low-poly capabilities. Best for complex models, optimized game assets, and geometry-focused production workflows. - `model` 'Lynx', required - `mode` 'model_to_optimize_uv', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` LynxModelToOptimizeUvParams - `assetId` string, uuid, required - `outputCount` integer - PantherTextToModelRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'text_to_model', required - `prompt` string, required - `files` object[] - `id` string, uuid, required - `params` PantherTextToModelParams - `symmetry` 'off' | 'auto' | 'on' - `topology` 'quad' | 'triangle' - `mesh_detail` 'Low poly' | 'High poly' - `assetId` string, uuid, required - `outputCount` integer - PantherImageToModelRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'image_to_model', required - `prompt` string - `files` object[], required: Exactly one input image. Role is not used. - `id` string, uuid, required - `params` PantherImageToModelParams - `symmetry` 'off' | 'auto' | 'on' - `topology` 'quad' | 'triangle' - `mesh_detail` 'Low poly' | 'High poly' - `face_count` '1K' | '2K' | '4K' | '8K' | '15K' - `generate_texture` 'no' | 'yes' - `refinement` 'off' | 'on' - `assetId` string, uuid, required - `outputCount` integer - PantherMultiviewToModelRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'multiview_to_model', required - `prompt` string - `files` object[], required: 1–4 views. `front` is required; roles must be unique across the array. - `id` string, uuid, required - `role` 'front' | 'back' | 'left' | 'right' - `params` PantherMultiviewToModelParams - `symmetry` 'off' | 'auto' | 'on' - `topology` 'quad' | 'triangle' - `mesh_detail` 'High poly' - `generate_texture` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - PantherModelToTextureRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'model_to_texture', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` PantherModelToTextureParams - `assetId` string, uuid, required - `outputCount` integer - PantherModelToSegmentRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'model_to_segment', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` PantherModelToSegmentParams - `assetId` string, uuid, required - `outputCount` integer - PantherModelToOptimizeMeshRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'model_to_optimize_mesh', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` PantherModelToOptimizeMeshParams - `assetId` string, uuid, required - `outputCount` integer - PantherModelToOptimizeUvRequest: PRODUCTION · HIGH-FIDELITY MESHES & TEXTURES — Professional 3D generation combining high-quality geometry with exceptional texture creation. Best for richly textured assets, detailed materials, and visually demanding production workflows. - `model` 'Panther', required - `mode` 'model_to_optimize_uv', required - `prompt` string - `files` object[] - `id` string, uuid, required - `params` PantherModelToOptimizeUvParams - `assetId` string, uuid, required - `outputCount` integer - OwlTextToImageRequest: VERSATILE · RELIABLE IMAGE GENERATION — Powerful, consistent image generation and editing across a wide range of styles and use cases. Best for everyday creative production, photorealistic visuals, and precise control over composition and details. - `model` 'Owl', required - `mode` 'text_to_image', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 10). - `id` string, uuid, required - `type` 'reference' - `params` OwlTextToImageParams - `speed` 'Quality' | 'Fast' - `aspect_ratio` '1:1' | '4:3' | '16:9' | '9:16' | '3:4' | '21:9' - `size` '1K' | '2K' | '4K' - `temperature` number - `top_p` number - `assetId` string, uuid, required - `outputCount` integer - SparrowTextToImageRequest: CREATIVE · CINEMATIC VISUALS — Expressive image generation with strong cinematic styling and artistic interpretation. Best for concept art, atmospheric environments, character design, and imaginative visual exploration. - `model` 'Sparrow', required - `mode` 'text_to_image', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 10). - `id` string, uuid, required - `type` 'reference' - `params` SparrowTextToImageParams - `speed` 'Quality' | 'Fast' - `assetId` string, uuid, required - `outputCount` integer - RavenTextToImageRequest: PREMIUM · HIGH-FIDELITY IMAGE PRODUCTION — Premium image generation and editing with precise detail preservation, accurate text rendering, and native transparent PNG output. Best for polished production assets, marketing visuals, icons, sprites, and reference-driven editing. - `model` 'Raven', required - `mode` 'text_to_image', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 16). - `id` string, uuid, required - `type` 'reference' - `params` RavenTextToImageParams - `quality` 'Low' | 'Medium' | 'High' - `aspect_ratio` '1:1' | '3:2' | '2:3' | '16:9' | '9:16' - `background` 'Auto' | 'Transparent' | 'Opaque' - `assetId` string, uuid, required - `outputCount` integer - OrcaTextToVideoRequest: STANDARD · RELIABLE VIDEO GENERATION — Reliable video generation with smooth, consistent motion. Best for everyday production, clean animations, simple transitions, and straightforward text-to-video workflows. - `model` 'Orca', required - `mode` 'text_to_video', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 3), `first_frame` (max 1), `last_frame` (max 1). Each file must include a `type` when using this mode. - `id` string, uuid, required - `type` 'reference' | 'first_frame' | 'last_frame' - `params` OrcaTextToVideoParams - `image_mode` 'Reference' | 'Keyframes' - `duration` '4s' | '6s' | '8s' - `resolution` '720p' - `aspect_ratio` '16:9' | '9:16' - `generate_audio` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - OrcaExtendVideoRequest: STANDARD · RELIABLE VIDEO GENERATION — Reliable video generation with smooth, consistent motion. Best for everyday production, clean animations, simple transitions, and straightforward text-to-video workflows. - `model` 'Orca', required - `mode` 'extend_video', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 1). - `id` string, uuid, required - `type` 'source_video' - `params` OrcaExtendVideoParams - `aspect_ratio` '16:9' | '9:16' - `assetId` string, uuid, required - `outputCount` integer - OrcaUpscaleVideoRequest: STANDARD · RELIABLE VIDEO GENERATION — Reliable video generation with smooth, consistent motion. Best for everyday production, clean animations, simple transitions, and straightforward text-to-video workflows. - `model` 'Orca', required - `mode` 'upscale_video', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 1). - `id` string, uuid, required - `type` 'source_video' - `params` OrcaUpscaleVideoParams - `target_width` number - `target_height` number - `preset` 'ultrafast' | 'superfast' | 'veryfast' | 'faster' | 'fast' | 'medium' | 'slow' | 'slower' | 'veryslow' - `crf` number - `assetId` string, uuid, required - `outputCount` integer - OrcaConcatVideosRequest: STANDARD · RELIABLE VIDEO GENERATION — Reliable video generation with smooth, consistent motion. Best for everyday production, clean animations, simple transitions, and straightforward text-to-video workflows. - `model` 'Orca', required - `mode` 'concat_videos', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 10). - `id` string, uuid, required - `type` 'source_video' - `params` OrcaConcatVideosParams - `assetId` string, uuid, required - `outputCount` integer - SeaHorseProTextToVideoRequest: PROFESSIONAL · HIGH-END VIDEO PRODUCTION — Professional multimodal video generation with clips up to 30 seconds, extensive reference control, motion guidance, and localized editing. Best for cinematic sequences, complex animations, and high-end creative production. Facial reference inputs are currently restricted to prevent deepfakes. Additional content moderation applies. - `model` 'Sea Horse Pro', required - `mode` 'text_to_video', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 30), `source_video` (max 10), `source_audio` (max 10). Each file must include a `type` when using this mode. - `id` string, uuid, required - `type` 'reference' | 'source_video' | 'source_audio' - `params` SeaHorseProTextToVideoParams - `auto_length` 'on' | 'off' - `duration` integer - `resolution` '480p' | '720p' - `aspect_ratio` '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '21:9' - `generate_audio` 'no' | 'yes' - `assetId` string, uuid, required - `outputCount` integer - SeaHorseProExtendVideoRequest: PROFESSIONAL · HIGH-END VIDEO PRODUCTION — Professional multimodal video generation with clips up to 30 seconds, extensive reference control, motion guidance, and localized editing. Best for cinematic sequences, complex animations, and high-end creative production. Facial reference inputs are currently restricted to prevent deepfakes. Additional content moderation applies. - `model` 'Sea Horse Pro', required - `mode` 'extend_video', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 1). - `id` string, uuid, required - `type` 'source_video' - `params` SeaHorseProExtendVideoParams - `aspect_ratio` '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '21:9' - `assetId` string, uuid, required - `outputCount` integer - SeaHorseProUpscaleVideoRequest: PROFESSIONAL · HIGH-END VIDEO PRODUCTION — Professional multimodal video generation with clips up to 30 seconds, extensive reference control, motion guidance, and localized editing. Best for cinematic sequences, complex animations, and high-end creative production. Facial reference inputs are currently restricted to prevent deepfakes. Additional content moderation applies. - `model` 'Sea Horse Pro', required - `mode` 'upscale_video', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 1). - `id` string, uuid, required - `type` 'source_video' - `params` SeaHorseProUpscaleVideoParams - `target_width` number - `target_height` number - `preset` 'ultrafast' | 'superfast' | 'veryfast' | 'faster' | 'fast' | 'medium' | 'slow' | 'slower' | 'veryslow' - `crf` number - `assetId` string, uuid, required - `outputCount` integer - SeaHorseProConcatVideosRequest: PROFESSIONAL · HIGH-END VIDEO PRODUCTION — Professional multimodal video generation with clips up to 30 seconds, extensive reference control, motion guidance, and localized editing. Best for cinematic sequences, complex animations, and high-end creative production. Facial reference inputs are currently restricted to prevent deepfakes. Additional content moderation applies. - `model` 'Sea Horse Pro', required - `mode` 'concat_videos', required - `prompt` string - `files` object[]: Accepted file types: `source_video` (max 10). - `id` string, uuid, required - `type` 'source_video' - `params` SeaHorseProConcatVideosParams - `assetId` string, uuid, required - `outputCount` integer - OrcaProTextToVideoRequest: ADVANCED · VIDEO CREATION — Advanced multimodal video creation with native audio. Best for guided scenes and short clips using text, a starting frame, or reference images. Currently produces ~10-second clips at 720p; existing-video input and editing are not supported. - `model` 'Orca Pro', required - `mode` 'text_to_video', required - `prompt` string, required - `files` object[]: Accepted file types: `reference` (max 6), `first_frame` (max 1). Each file must include a `type` when using this mode. - `id` string, uuid, required - `type` 'reference' | 'first_frame' - `params` OrcaProTextToVideoParams - `image_mode` 'Reference' | 'Keyframes' - `aspect_ratio` '16:9' | '9:16' - `assetId` string, uuid, required - `outputCount` integer - ModelLibraryGenerationRequest: A studio-enabled Model Library model. Use the engine id, input key, parameter keys and file types returned by GET /v1/engines. - `model` string, required - `mode` string, required - `prompt` string - `files` object[] - `id` string, uuid, required - `role` 'front' | 'back' | 'left' | 'right' - `type` string - `params` object - `assetId` string, uuid, required - `outputCount` integer ## Response `201` Generation created and queued - Generation - `id` string, uuid, required - `name` string, required - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED', required - `model` string - `mode` string - `assetId` string, uuid, nullable - `outputs` Output[] - `id` string, uuid, required - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED', required - `type` string - `progress` number - `url` string, nullable: Temporary output URL when available. Fetch GET /v1/generations/{id} again to obtain a fresh URL; do not persist this URL as a permanent asset link. - `createdAt` string, date-time - `finishedAt` string, date-time, nullable - `errorCode` string, nullable - `outputCount` number - `moodBoard` boolean - `createdAt` string, date-time, required ## Other responses - `400`: Validation error - `401`: Authentication required or invalid - `403`: Insufficient balance or trial expired - `404`: Resource unavailable or API feature disabled - `429`: Rate limit exceeded - `500`: Unexpected server error - `503`: Service temporarily unavailable --- [API](https://skmtc.dev/virtuall/apis/virtuall-external-api.md) - [All operations](https://skmtc.dev/virtuall/apis/virtuall-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/virtuall/apis/virtuall-external-api/revisions/2b3a30238ce0?raw)