---
title: "Create generation request based on model. Returns immediately with a taskId"
method: POST
path: "/api/v1/generation/create"
tags: ["Generations"]
---

# Create generation request based on model. Returns immediately with a taskId

`POST /api/v1/generation/create`

## Request

- Base URL: `https://api.api-stock.com`
- URL: `https://api.api-stock.com/api/v1/generation/create`
- Auth: HTTP bearer

## Headers

- `idempotency-key` string, required
- `x-max-cost-micro-usd` string, required

## Request body

- CreateGenerationRequestDto
  - `model` 'veo3.1-fast' | 'veo3.1-quality' | 'veo3.1-lite' | 'nano-banana' | 'nano-banana-pro' | 'nano-banana-2' | 'nano-banana-2.1' | 'nano-banana-2-lite' | 'grok-imagine-1.5-video' | 'grok-imagine-1.5-image' | 'grok-imagine-2.0-image' | 'seedance-2.0' | 'seedance-2.0-fast' | 'seedance-2.0-mini' | 'seedance-2.5' | 'seedance-2.5-spicy' | 'seedance-1-5-pro' | 'gpt-image-2' | 'gpt-image-2.5-sunburst' | 'gpt-image-2.5-flare' | 'kling-3.0-motion-control' | 'kling-3.0' | 'kling-4.0' | 'pixverse-v6' | 'seedream-5-0-lite' | 'seedream-5-0-flash' | 'seedream-5-0-pro' | 'seedream-4-5' | 'wan2.7-video' | 'wan3.0-video' | 'wan3.0-video-prime' | 'wan3.0-video-pro' | 'flux-3-video' | 'flux-3-image' | 'gemini-omni-1.1-flash' | 'minimax-h3' | 'agnes-video-2.5' | 'z-image' | 'wan2.7-image' | 'wan2.7-image-pro' | 'midjourney' | 'midjourney-video' | 'suno', required: Model of generation. Retired ids are still accepted and map to the current model: `doubao-seedance-2.0` → `seedance-2.0`, `doubao-seedance-2.0-fast` → `seedance-2.0-fast`, `doubao-seedance-2.0-mini` → `seedance-2.0-mini`, `doubao-seedance-2.5` → `seedance-2.5`, `doubao-seedance-1-5-pro` → `seedance-1-5-pro`, `doubao-seedream-4-5` → `seedream-4-5`, `doubao-seedream-5-0-lite` → `seedream-5-0-lite`, `doubao-seedream-5-0-pro` → `seedream-5-0-pro`.
  - `input` union, required: Generation parameters (structure depends on the model)
    - Veo3InputDto
      - `prompt` string, required: User's prompt
      - `aspectRatio` '16:9' | '9:16': Aspect ratio
      - `urls` string[]: Image URLs for video generation
      - `resolution` '720p' | '1080p' | '4k': Video resolution quality
      - `generationType` 'frame' | 'reference': Generation type for VEO3 model
    - Veo3LiteInputDto
      - `prompt` string, required: User's prompt
      - `aspectRatio` '16:9' | '9:16': Aspect ratio
      - `resolution` '720p' | '1080p' | '4k': Video resolution quality
    - NanoBananaInputDto
      - `prompt` string, required: User's prompt
      - `urls` string[]: Reference image URLs for image generation or editing
      - `size` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9' | '1:4' | '1:8' | '4:1' | '8:1': Output image size ratio
      - `resolution` '512px' | '1K' | '2K' | '4K': Output image resolution
    - NanoBanana21InputDto
      - `prompt` string, required: User's prompt
      - `urls` string[]: Reference image URLs for image generation or editing
      - `size` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9' | '1:4' | '1:8' | '4:1' | '8:1': Output image size ratio
      - `resolution` '1K' | '2K' | '4K': Output image resolution
    - GrokImagineInputDto
      - `prompt` string, required: Video content description
      - `size` '16:9' | '9:16' | '1:1' | '3:2' | '2:3': Video aspect ratio / size
      - `duration` 6 | 10 | 15 | 20 | 25 | 30: Video duration in seconds
      - `resolution` '480p' | '720p': Video resolution
      - `urls` string[]: Reference image URLs for image-to-video mode
    - GrokImagineImageInputDto
      - `prompt` string, required: Text description for image generation
      - `size` '1:1' | '16:9' | '9:16' | '3:2' | '2:3': Image aspect ratio
      - `urls` string[]: Reference image URLs for image-to-image mode
    - GrokImagine2ImageInputDto
      - `prompt` string, required: Text description for image generation
      - `size` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '9:16' | '16:9': Image aspect ratio
    - Flux3ImageInputDto
      - `prompt` string, required: Text description or image editing instructions. Layout and bounding-box instructions may be included in the prompt.
      - `urls` string[]: Reference image URLs for editing or multi-image guidance (up to 10 images). Omit for text-to-image generation.
      - `size` 'auto' | '21:9' | '2:1' | '16:9' | '3:2' | '7:5' | '4:3' | '5:4' | '1:1' | '4:5' | '3:4' | '5:7' | '2:3' | '9:16' | '1:2' | '9:21': Image aspect ratio. Auto follows the first reference image, or the prompt when generating from text.
      - `resolution` '768SQ' | '1K' | '1.5K' | '2K' | '4K': Output resolution tier; determines the per-image price.
      - `grounding` boolean: Allow web and image search before generation. Reference images and search do not add a separate charge.
    - SeedanceInputDto
      - `prompt` string: Video content description. Required unless image or video reference media is provided (maximum 4000 characters).
      - `duration` number: Video duration in seconds (4-15)
      - `size` 'adaptive' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9': Video aspect ratio. adaptive follows the input image or video.
      - `resolution` '480p' | '720p' | '1080p' | '4k': Output resolution and per-second billing tier
      - `seed` number: Random seed for controlling randomness
      - `generateAudio` boolean: Whether to generate audio
      - `imageUrls` string[]: Public image URLs for image-to-video (maximum 9). Very narrow or wide images may be padded to a width-to-height ratio of 0.4–2.5 without cropping. In first-frame mode, padding becomes part of the frame.
      - `imageWithRoles` SeedanceImageWithRole[]: Images with explicit first_frame / last_frame roles. Cannot be combined with other reference-media fields.
        - `url` string, required: Image URL
        - `role` 'first_frame' | 'last_frame', required: Image role: first_frame or last_frame
      - `videoUrls` string[]: Public reference-video URLs (maximum 3; total duration must be more than 1.8s and less than 15.2s). Their duration is probed before charging.
      - `audioUrls` string[]: Public reference-audio URLs (maximum 3; 15 seconds total). Requires imageUrls or videoUrls.
      - `tools` SeedanceToolDto[]: Optional enhancements such as web search grounding
        - `type` 'web_search', required: Generation enhancement tool
    - Seedance25InputDto
      - `prompt` string, required: Video prompt. Reference images, videos and audio positionally in the prompt.
      - `duration` number: Output duration in seconds (4-30). For reference-video jobs, input and output seconds use the reference-input tariff.
      - `size` 'adaptive' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '21:9': Output aspect ratio. First/last-frame and extend jobs require adaptive.
      - `resolution` '480p' | '720p' | '1080p': Output resolution and per-second billing tier
      - `generateAudio` boolean: Whether the generated video includes audio
      - `seed` number: Random seed; identical output is not guaranteed
      - `outputFormat` 'mp4' | 'mov': Output video container
      - `omniReferenceTaskType` 'auto' | 'reference' | 'extend': Optional task-type hint. edit is unavailable until variable-duration billing settlement is supported.
      - `imageUrls` string[]: Reference image URLs (maximum 30 across both image fields). Very narrow or wide images may be padded to a width-to-height ratio of 0.4–2.5 without cropping. In first-frame mode, padding becomes part of the frame.
      - `imageWithRoles` Seedance25ImageWithRoleDto[]: Images with explicit first_frame, last_frame or reference_image roles
        - `url` string, required: Public image URL
        - `role` 'first_frame' | 'last_frame' | 'reference_image', required: Frame or reference role assigned to this image
      - `videoUrls` string[]: Public reference-video URLs (maximum 10; 2-30 seconds each and 30 seconds total). Their duration is probed before charging.
      - `audioUrls` string[]: Reference audio URLs (maximum 10; 30 seconds total)
      - `tools` Seedance25ToolDto[]: Optional enhancements such as web search grounding
        - `type` 'web_search', required: Generation enhancement tool
    - Seedance25SpicyInputDto
      - `prompt` string, required: Video prompt. Reference images, videos and audio positionally in the prompt.
      - `duration` number: Output duration in seconds (4-30). For reference-video jobs, input and output seconds use the reference-input tariff.
      - `size` 'adaptive' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '21:9': Output aspect ratio. First-frame animation and extend jobs require adaptive.
      - `resolution` '480p' | '720p' | '1080p': Output resolution and per-second billing tier
      - `generateAudio` boolean: Whether the generated video includes audio
      - `omniReferenceTaskType` 'auto' | 'reference' | 'extend': auto selects the mode from the supplied media; reference uses all supplied references; extend continues a source video and requires videoUrls. Video editing is unavailable.
      - `imageUrls` string[]: Reference image URLs (maximum 30). One image without other media animates the first frame; use reference mode to treat it as a style reference. Images outside a width-to-height ratio of 0.4–2.5 are padded without cropping when preparation succeeds. In first-frame mode, padding becomes part of the frame.
      - `videoUrls` string[]: Public reference-video URLs (maximum 10; 2-30 seconds each and 30 seconds total). Their duration is probed before charging.
      - `audioUrls` string[]: Reference audio URLs (maximum 10; 30 seconds total). Requires at least one reference image or video.
      - `tools` Seedance25ToolDto[]: Optional enhancements such as web search grounding
        - `type` 'web_search', required: Generation enhancement tool
    - Seedance15ProInputDto
      - `prompt` string: Video content description. Required for text-to-video; optional when image input is provided (maximum 4000 characters).
      - `duration` 4 | 8 | 12: Video duration in seconds
      - `size` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9': Video aspect ratio
      - `resolution` '480p' | '720p' | '1080p': Video resolution
      - `seed` number: Random seed for controlling randomness
      - `generateAudio` boolean: Whether to generate audio
      - `imageUrls` string[]: Public image URLs for image-to-video (maximum 9)
      - `imageWithRoles` SeedanceImageWithRole[]: Images with explicit first_frame / last_frame roles. Cannot be combined with other reference-media fields.
        - `url` string, required: Image URL
        - `role` 'first_frame' | 'last_frame', required: Image role: first_frame or last_frame
      - `cameraFixed` boolean: Whether to fix the camera position
    - GptImageInputDto
      - `prompt` string, required: User's prompt
      - `urls` string[]: Reference image URLs (URLs or base64 data URIs) for image-to-image mode
      - `size` 'auto' | '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3' | '5:4' | '4:5' | '2:1' | '1:2' | '3:1' | '1:3' | '21:9' | '9:21': Output image aspect ratio. For GPT Image 2.5 models, 1:3 and 3:1 require 2k or 4k resolution.
      - `resolution` '1k' | '2k' | '4k': Output image resolution
    - KlingMotionControlInputDto
      - `prompt` string: Optional scene prompt
      - `imageUrls` string[], required: Reference image URL (exactly one). JPG/JPEG/PNG, max 10MB. An image whose longer side exceeds 3850px is downscaled automatically
      - `videoUrls` string[], required: Reference video URL (exactly one). MP4/MOV, max 100MB
      - `characterOrientation` 'image' | 'video', required: Character orientation mode. Determines whose orientation drives the motion transfer
      - `resolution` '720p' | '1080p': Output resolution
    - Kling3InputDto
      - `prompt` string, required: Video content description
      - `resolution` '720p' | '1080p' | '4k': Video resolution tier (affects pricing)
      - `duration` number: Video duration in seconds (3-15). Billed per second
      - `aspectRatio` '16:9' | '9:16' | '1:1': Video aspect ratio. Ignored in image-to-video mode — the ratio is taken from the input frame
      - `generateAudio` boolean: Whether to generate a native audio track (increases pricing on 720p and 1080p)
      - `imageUrls` string[]: Input frames for image-to-video. One URL is used as the first frame, two as first + last frame
    - Kling4InputDto
      - `prompt` string: Describe the scene. Use @Image1 / @Element1 for references. Required unless multiShots is supplied; mutually exclusive with multiShots.
      - `videoMode` 'elements' | 'start_end_frame' | 'transform' | 'video_reference': Omit for pure text-to-video. Use elements for references, start_end_frame for keyframes, transform or video_reference for a source video.
      - `resolution` '720p' | '1080p': Output resolution (4K is not available)
      - `duration` number: Output seconds, 3–30. Ignored with source video (its probed duration is billed) or multiShots (shot durations are summed).
      - `aspectRatio` 'auto' | '16:9' | '9:16' | '1:1' | '21:9': Aspect ratio; must be auto with a source video. Keyframes determine their own ratio.
      - `generateAudio` boolean: Generate native stereo audio (included in the price)
      - `keepAudio` boolean: Preserve source video audio
      - `imageUrls` string[]: Raw references (up to 10); address as @Image1, @Image2. Requires elements, transform or video_reference mode.
      - `startImageIndex` number: 1-based imageUrls index anchoring the first frame (elements mode)
      - `elements` Kling4ElementDto[]: Subject elements: { description?: string, type?: image | video, imageUrls?: string[1..4], videoUrl?: string }. Up to 7, at most 3 video elements. Images and elements together: at most 15, or 14 with source video.
        - `description` string: Subject description (up to 100 characters)
        - `type` 'image' | 'video': Element media type
        - `imageUrls` string[]: Image element references (1–4 URLs)
        - `videoUrl` string: Video element source URL
      - `startFrameUrl` string: Required first frame in start_end_frame mode
      - `keyframeUrls` string[]: Ordered middle frames (up to 8) in start_end_frame mode; at most 10 total frames
      - `endFrameUrl` string: Optional last frame in start_end_frame mode
      - `videoUrl` string: Source video for transform / video_reference. Duration is probed before charging; 3–10 seconds for transform, 3–30 for video_reference. Transform needs a short side of at least 700px.
      - `multiShots` Kling4ShotDto[]: 2–6 scenes totalling 3–30 seconds; replaces prompt and duration. Only text-to-video and elements modes.
        - `prompt` string, required: Scene description
        - `duration` number, required: Scene duration in seconds; all shots must total 3–30 seconds
    - PixverseInputDto
      - `prompt` string, required: Video content description
      - `resolution` '360p' | '540p' | '720p' | '1080p': Video resolution tier (affects pricing)
      - `duration` number: Video duration in seconds (1-15). Transition mode only supports 5 or 8
      - `size` '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '2:3' | '3:2' | '21:9': Video aspect ratio. Only effective in text-to-video and multi-reference fusion modes
      - `seed` number: Random seed
      - `negativePrompt` string: Negative prompt to exclude unwanted content
      - `audio` boolean: Whether to generate an audio track (increases pricing)
      - `motionMode` 'normal': Motion mode. pixverse-v6 only supports "normal"
      - `generateMultiClipSwitch` boolean: Whether to generate a multi-clip continuous video. Only supported in text-to-video and image-to-video modes
      - `imageUrls` string[]: Input image URL array for image-to-video mode (only the first image is used)
      - `firstFrameImage` string: First frame image URL for transition mode. Must be provided together with lastFrameImage
      - `lastFrameImage` string: Last frame image URL for transition mode. Must be provided together with firstFrameImage
      - `imgReferences` string[]: Reference image URLs for multi-reference fusion mode (1-7 images)
      - `extendFromTaskId` string: Source task ID for video extension mode
    - SeedreamInputDto
      - `prompt` string, required: Text description for image generation
      - `urls` string[]: Reference image URLs (URLs or base64 data URIs) for image-to-image mode
      - `size` '1:1' | '4:3' | '3:4' | '16:9' | '9:16' | '3:2' | '2:3' | '21:9' | '9:21' | 'auto': Image aspect ratio
      - `resolution` '1K' | '1.5K' | '2K' | '3K' | '4K': Image resolution
      - `outputFormat` 'jpeg' | 'png': Output image format (Seedream 5.0 Lite / Pro / Flash only; ignored by other models)
      - `promptOptimizeMode` 'standard' | 'fast': Prompt optimization mode (seedream-4-5 only; ignored by other models)
    - Seedream50FlashInputDto
      - `prompt` string, required: Text description for image generation or editing (up to 5000 characters)
      - `urls` string[]: Up to 10 reference image URLs for image-to-image mode
      - `size` '1:1' | '4:3' | '3:4' | '16:9' | '9:16' | '3:2' | '2:3' | '21:9': Image aspect ratio
      - `resolution` '1K' | '1.5K' | '2K': Image resolution
      - `outputFormat` 'jpeg' | 'png': Output image format
    - Wan27VideoInputDto
      - `prompt` string: Text prompt. Required for text-to-video, reference-to-video and edit-video; optional for image-to-video.
      - `imageUrls` string[]: Image-to-video frames. First URL is the starting frame, an optional second URL is the ending frame. Providing this selects the image-to-video workflow.
      - `referenceImageUrls` string[]: Reference images for the reference-to-video workflow. Requires a prompt.
      - `referenceVideoUrls` string[]: Reference videos for the reference-to-video workflow. Requires a prompt.
      - `editVideoUrl` string: Source video to edit. Providing this selects the edit-video workflow (requires a prompt).
      - `referenceImageUrl` string: Optional reference image guiding the edit-video workflow.
      - `continueVideoUrl` string: Source video to continue or extend. Selects the video-continuation workflow. Cannot be combined with imageUrls or audioUrl. Supported duration is 2-10 seconds.
      - `audioUrl` string: Optional audio URL (text-to-video and image-to-video workflows).
      - `size` '16:9' | '9:16' | '1:1' | '4:3' | '3:4': Aspect ratio (text-to-video, reference-to-video and edit-video). Ignored for image-to-video, where it is derived from the input frames.
      - `resolution` '720p' | '1080p': Output resolution
      - `duration` number: Video duration in seconds (2-15). Allowed values depend on the resolved workflow: text-to-video accepts 5/10/15, image-to-video 2-15, reference-to-video 2-10, edit-video 0 or 2-10 (0 lets PoYo detect the source video duration).
      - `multiShots` boolean: Enable multi-shot generation (image, reference and edit workflows).
      - `audioSetting` string: Audio setting for the edit-video workflow.
      - `seed` number: Random seed for controlling randomness
      - `enableSafetyChecker` boolean: Enable the model's safety checker
    - Wan30VideoInputDto
      - `prompt` string: Text description. Required unless at least one media input is supplied. In reference mode you can address assets positionally with "图N / 视频N / 音频N" labels; indices run per media type.
      - `imageUrls` string[]: Image URLs without explicit roles. In the frame family the first item is the start frame and an optional second is the end frame; in the reference family every item is a reference image (up to 10).
      - `imageWithRoles` Wan30ImageWithRoleDto[]: Images with explicit roles. Use this when you need first/last frame or reference images stated outright rather than inferred from order.
        - `url` string, required: Image address (public URL or data:image/...;base64,...)
        - `role` 'first_frame' | 'last_frame' | 'reference_image': Role of the image. first_frame/last_frame belong to the frame family, reference_image to the reference family; the two cannot be mixed.
      - `videoUrls` string[]: Reference videos, up to 5 clips of 1-15s each (total <= 15s). Input video duration plus the requested output duration must stay within 30 seconds.
      - `audioUrls` string[]: Reference audio, up to 5 clips of 1-15s each (total <= 15s).
      - `fileUrl` string: Reference document driving the generation (docx/xlsx/pptx/pdf/txt/md and similar, <=100MB, <=50 pages). Cannot be combined with linkUrl. A prompt is optional when this is supplied.
      - `linkUrl` string: Public, login-free web page to turn into a video. Cannot be combined with fileUrl.
      - `generationType` 'frame' | 'reference': How bare imageUrls are classified: frame (first/last frame) or reference. Omit to let it be inferred — reference when the request already carries reference-family inputs, frame otherwise.
      - `size` 'adaptive' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Aspect ratio. `adaptive` lets the model pick one from the inputs.
      - `resolution` '480p' | '720p' | '1080p': Output resolution. Each tier is billed at its own per-second rate, so 1080p costs four times 480p for the same duration.
      - `duration` number: Duration in seconds (2-30). Billing is per second at the resolution's rate. With reference videos, total input video duration plus this value must be at most 30 seconds.
      - `audio` boolean: Include an audio track in the output.
      - `seed` number: Random seed for controlling randomness
    - Wan30VideoProInputDto
      - `prompt` string: Text description. Required unless at least one media input is supplied. In reference mode you can address assets positionally with "图N / 视频N / 音频N" labels; indices run per media type.
      - `imageUrls` string[]: Image URLs without explicit roles. In the frame family the first item is the start frame and an optional second is the end frame; in the reference family every item is a reference image (up to 10).
      - `imageWithRoles` Wan30ImageWithRoleDto[]: Images with explicit roles. Use this when you need first/last frame or reference images stated outright rather than inferred from order.
        - `url` string, required: Image address (public URL or data:image/...;base64,...)
        - `role` 'first_frame' | 'last_frame' | 'reference_image': Role of the image. first_frame/last_frame belong to the frame family, reference_image to the reference family; the two cannot be mixed.
      - `videoUrls` string[]: Reference videos, up to 5 clips of 1-15s each (total <= 15s). Input video duration plus the requested output duration must stay within 30 seconds.
      - `audioUrls` string[]: Reference audio, up to 5 clips of 1-15s each (total <= 15s).
      - `fileUrl` string: Reference document driving the generation (docx/xlsx/pptx/pdf/txt/md and similar, <=100MB, <=50 pages). Cannot be combined with linkUrl. A prompt is optional when this is supplied.
      - `linkUrl` string: Public, login-free web page to turn into a video. Cannot be combined with fileUrl.
      - `generationType` 'frame' | 'reference': How bare imageUrls are classified: frame (first/last frame) or reference. Omit to let it be inferred — reference when the request already carries reference-family inputs, frame otherwise.
      - `size` 'adaptive' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Aspect ratio. `adaptive` lets the model pick one from the inputs.
      - `duration` number: Duration in seconds (2-30). Billing is per second at the resolution's rate. With reference videos, total input video duration plus this value must be at most 30 seconds.
      - `audio` boolean: Include an audio track in the output.
      - `resolution` '480p' | '720p' | '1080p' | '2K' | '4K': Output resolution. Billing is per second, including reference video seconds.
      - `promptExtend` boolean: Let the model expand the prompt. Set false to keep the literal prompt.
    - Flux3VideoInputDto
      - `prompt` string, required: Scene description: subject, action, camera movement, dialogue and sound
      - `resolution` '720p' | '1080p': Video resolution (affects pricing). Draft mode supports 720p only
      - `duration` number: Video duration in seconds (5-20). Billed per second
      - `aspectRatio` 'auto' | '21:9' | '2:1' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Video aspect ratio. `auto` lets the model choose from the prompt and input frames
      - `imageUrls` string[]: Keyframes for image-to-video, in playback order. One image is the start frame, two are start + end, three or more are spread evenly across the clip
      - `videoUrl` string: Source video (mp4) to continue. Continuation is billed at a higher per-second rate and cannot be combined with imageUrls
      - `draft` boolean: Draft mode: a fast, low-quality 720p preview at about a third of the price
      - `safetyTolerance` number: Moderation tolerance from 0 (strictest) to 4 (most permissive)
    - GeminiOmni11InputDto
      - `prompt` string, required: Describe the scene, motion and sound.
      - `imageUrls` string[]: First frame and optional last frame. Cannot be combined with reference inputs.
      - `referenceImageUrls` string[]: Reference images (up to 7; up to 5 with a reference video). Cannot be combined with imageUrls.
      - `referenceVideoUrls` string[]: One source video, 3–10 seconds. Output follows source duration and is billed per generation. Cannot be combined with imageUrls.
      - `aspectRatio` '16:9' | '9:16': Output aspect ratio
      - `duration` 4 | 6 | 8 | 10: Output duration. Ignored with a source video, which uses a flat per-generation price.
      - `resolution` '360p' | '720p' | '1080p' | '4k': Output resolution; 1080p and 4K are upscaled outputs.
    - MinimaxH3InputDto
      - `prompt` string, required: Describe the scene, motion and audio. Refer to supplied images and audio in the prompt.
      - `aspectRatio` '16:9' | '9:16': Video aspect ratio
      - `imageUrls` string[]: Reference image URLs (up to 9). The first 5 are free; each additional image is billed separately per request.
      - `audioUrls` string[]: Reference audio URLs (up to 3), free of additional charge.
      - `resolution` '480p' | '768p' | '1080p': Output resolution; 1080p supports at most 10 seconds.
      - `duration` number: Output duration in seconds (1–15; at most 10 at 1080p).
      - `seed` number: Random seed
    - AgnesVideoInputDto
      - `prompt` string, required: Describe the scene, motion and audio. Refer to supplied images and audio in the prompt.
      - `aspectRatio` '16:9' | '9:16' | '21:9' | '4:3' | '1:1' | '3:4': Video aspect ratio
      - `imageUrls` string[]: Reference image URLs (up to 9). Included in the per-second price.
      - `audioUrls` string[]: Reference audio URLs (up to 3), free of additional charge.
      - `resolution` '720p' | '1080p' | '2k': Output video resolution.
      - `duration` number: Output duration in seconds (1–12).
      - `seed` number: Random seed
    - ZImageInputDto
      - `prompt` string, required: Text description for image generation
      - `urls` string[]: Optional reference image for editing (exactly one URL). Providing it switches the request to image editing.
      - `size` '1:1' | '4:3' | '3:4' | '16:9' | '9:16': Image aspect ratio. Required for text-to-image; optional for image editing (defaults to following the reference image).
      - `enableSafetyChecker` boolean: Enable the model's safety checker (defaults to true)
    - Wan27ImageInputDto
      - `prompt` string, required: Text description for image generation
      - `urls` string[]: Reference images for editing (1-4 URLs). Providing them switches the request to edit mode. Order matters: reference them as image 1, image 2, etc. in the prompt.
      - `size` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3': Output aspect ratio (ignored when width + height are provided)
      - `width` number: Custom output width in pixels (requires height). Overrides size.
      - `height` number: Custom output height in pixels (requires width). Overrides size.
      - `seed` number: Random seed for reproducible output
    - MidjourneyInputDto
      - `action` 'imagine' | 'edits' | 'blend' | 'describe' | 'upscale' | 'variation' | 'high-variation' | 'low-variation' | 'reroll' | 'zoom' | 'pan' | 'inpaint' | 'modal' | 'remix-strong' | 'remix-subtle': Midjourney action / endpoint. Defaults to 'imagine' (text-to-image). Follow-up actions reference a previous generation via 'parentTaskId'.
      - `prompt` string: Prompt; required for imagine/edits. Native MJ flags allowed (e.g. '--ar 16:9 --v 6.1'). Structured body fields override prompt flags.
      - `imageUrls` string[]: Image URLs or base64 data URIs. Used as: image-guided (imagine), source (edits), blend set (2–4), describe (1).
      - `parentTaskId` string: Parent generation id (a previous 'midjourney' generation in our system) for follow-up actions (upscale/variation/reroll/zoom/pan/inpaint/modal/remix). The upstream task id is resolved from it.
      - `index` number: Tile index (1–4) for upscale/variation/zoom/pan/inpaint/remix when 'customId' is not provided.
      - `customId` string: Raw MJ button id for the action; when set, 'index'/'direction' matching is skipped.
      - `speed` 'relax' | 'fast' | 'turbo': Speed mode. 'relax' (default) adds no billing suffix.
      - `direction` 'left' | 'right' | 'up' | 'down': Pan direction (action=pan).
      - `zoomRatio` number: Zoom factor (action=zoom). < 2 → Zoom Out 1.5x; omitted or >= 2 → 2x.
      - `maskUrl` string: Mask image URL or base64 (action=modal). White = repaint, transparent = keep.
      - `dimensions` 'SQUARE' | 'PORTRAIT' | 'LANDSCAPE': Aspect preset for blend (action=blend); overridden by 'size'.
      - `size` string: Aspect ratio 'w:h' (--ar), e.g. '16:9', '1:1', '21:9'.
      - `quality` '0.25' | '0.5' | '1' | '2': Quality (--q).
      - `style` string: Style (--style), e.g. 'raw'.
      - `version` '8.1' | '7' | '6.1' | '5.2' | '5.1': Main MJ version (--v). With 'niji: true' and '7'/'6' it normalizes to Niji.
      - `seed` number: Seed (--seed).
      - `negativePrompt` string: Negative prompt (--no), e.g. 'ugly, blurry'.
      - `stylize` number: Stylize (--s), 0–1000.
      - `chaos` number: Chaos (--c), 0–100.
      - `weird` number: Weird (--w), 0–3000.
      - `tile` boolean: Tile mode (--tile).
      - `niji` boolean: Niji switch (--niji). Use with version 7/6.
      - `iw` number: Image weight (--iw), 0–3.
      - `cw` number: Character weight (--cw), 0–100.
      - `sw` number: Style weight (--sw), 0–1000.
      - `cref` string: Character reference URL (--cref).
      - `sref` string: Style reference URL (--sref).
      - `dref` string: Depth reference URL (--dref).
      - `dw` number: Depth weight (--dw), 0–100.
      - `repeat` number: Repeat (--repeat), 2–40.
      - `raw` boolean: Raw style (--raw), v5.1+.
      - `draft` boolean: Draft mode (--draft), v7+.
      - `hd` boolean: HD mode (--hd), v8/v8.1 only.
      - `stop` number: Early stop (--stop), 10–100; v5–6.1 / niji 5–6 only.
      - `extra` string: Escape hatch appended to the prompt verbatim (any '--xxx').
    - MidjourneyVideoInputDto
      - `prompt` string: Video prompt; optional when reusing a parent task.
      - `imageUrls` string[]: First-frame image (1 image, URL or base64). One of imageUrls / parentTaskId.
      - `parentTaskId` string: Parent generation id (a SUCCESS 'midjourney' imagine generation) to reuse as the source. One of imageUrls / parentTaskId.
      - `index` number: Which tile of the parent imagine grid is the first frame (0–3).
      - `videoType` 'vid_1.1_i2v_480' | 'vid_1.1_i2v_720' | 'vid_1.1_i2v_start_end_480' | 'vid_1.1_i2v_start_end_720': Resolution / mode tier. 720 tiers bill at the 720p rate.
      - `animateMode` 'manual' | 'auto': Animation mode. 'auto' requires parentTaskId + index.
      - `motion` 'low' | 'high': Motion amount. No billing impact.
      - `batchSize` 1 | 2 | 4: Batch size (1 / 2 / 4). Billed × N.
      - `endUrl` string: End frame; when set, videoType auto-upgrades to a start/end tier.
    - SunoInputDto
      - `action` 'music' | 'extend' | 'cover' | 'add-instrumental' | 'add-vocals' | 'sound' | 'stems' | 'stems-all' | 'wav' | 'lyrics' | 'voice' | 'timestamped-lyrics' | 'boost-style' | 'music-cover' | 'replace-section' | 'music-video' | 'inspo' | 'upload' | 'remaster' | 'add-stem' | 'vox' | 'remove-section' | 'crop' | 'fade-in' | 'fade-out' | 'adjust-speed' | 'concat' | 'mashup' | 'sample' | 'midi' | 'bpm' | 'custom-model': Suno operation
      - `mv` string: Engine version. Audio actions: v6 (default) | v6-wild | v6-mini | custom. The retired versions v3.5 … v5.5 are still accepted and run on v6. lyrics: remi-v1 | default. Not used by stems/stems-all/wav/voice. variety, maxMode, audioFormat, duration and customModelId need a V6 engine (any value except custom).
      - `custom` boolean: false for simple mode, true for custom mode
      - `gptDescriptionPrompt` string: Simple mode: song / effect description (with optional lyrics)
      - `prompt` string: Custom mode: detailed lyrics / prompt (also the lyrics or sound description)
      - `tags` string: Custom mode: genre / style tags
      - `title` string: Title for the result
      - `makeInstrumental` boolean: Generate an instrumental-only track
      - `negativeTags` string: Styles to avoid (custom mode / sound)
      - `personaId` string: ID of a custom voice (persona) to sing the generated music
      - `customModel` SunoCustomModelDto
        - `name` string, required: Custom model name
        - `audioUrls` string[], required: Audio URLs to train on (6–24)
      - `customModelId` string: Id of a reusable custom model created by the `custom-model` action (its `output.customModelId`). Generates in that model's style; cannot be combined with mv or personaId.
      - `variety` 'off' | 'normal' | 'high' | 'extra' | 'max': Style variation: off | normal | high | extra | max. V6 generative actions.
      - `maxMode` boolean: Max mode: higher-quality V6 generation, billed at twice the regular price. Requires custom mode, except on inspo and replace-section.
      - `audioFormat` 'mp3' | 'm4a' | 'wav': Output audio format: mp3 | m4a | wav. V6 generative actions plus sound, remaster, stems and stems-all.
      - `duration` number: music / extend / cover: target length in seconds (10–360), custom mode only. The actual length is decided by the model.
      - `audioUrl` string: Audio file URL to operate on
      - `continueAt` number: extend: time in seconds where the extension should begin (at least 1 for a sourceTaskId or audioUrl source)
      - `sourceTaskId` string: Reference to one of your prior Suno generations (its taskId), used by stateful actions such as extend, music-cover, replace-section, timestamped-lyrics, music-video, voice and wav.
      - `audioId` string: The track to operate on, identified by its id (as returned in a prior generation's `output.tracks[].audioId`). A generation usually produces 2 tracks; omit to use the first.
      - `fullLyrics` string: replace-section: complete lyrics for the whole track after the edit
      - `author` string: music-video: artist / creator name on the cover (max 50)
      - `domainName` string: music-video: brand / site watermark at the bottom (max 50)
      - `aspectRatio` '9:16' | '16:9' | '1:1' | '3:4' | '4:3': music-video: output aspect ratio
      - `backgroundColors` string[]: music-video: 1–4 hex colors for the blurred gradient backdrop (e.g. ["#1B2635", "#8A6A4F"])
      - `imageUrl` string: music-video: cover image URL to show inside the ring (default: the source track's cover art when available)
      - `quality` 'compact' | 'high' | 'max': music-video: output quality. `compact` — small share-friendly file (~5MB / 3 min); `high` — sharper 720p-class output at roughly double the size; `max` — 1080p-class, ~4× compact
      - `startS` number: Start time (seconds) of the affected range. Used by remove-section / crop / sample (the range), replace-section (the infill range) and vox / voice-from-track (the vocal window).
      - `endS` number: End time (seconds) of the affected range (> startS). See startS for the actions that use it.
      - `bpm` number: sound: tempo in BPM
      - `key` string: sound: musical key (Major C–B; Minor Cm–Bm)
      - `type` 'one-shot' | 'loop': sound: 'one-shot' or 'loop' (defaults to one-shot)
      - `voiceAudioUrl` string: voice: URL to the voice recording
      - `verificationAudioUrl` string: voice: URL to the verification-phrase recording
      - `phraseId` string: voice: phrase ID from the verification-phrase endpoint
      - `name` string: voice / custom-model: name
      - `description` string: voice: description
      - `styles` string: voice: genre tags (e.g. 'funk edm')
      - `singerSkillLevel` 'Beginner' | 'Intermediate' | 'Advanced' | 'Professional': voice: singer skill level
      - `audioUrls` string[]: Public audio URLs. inspo: 1–4 inspiration references; custom-model: 6–24 training tracks (MP3, WAV or M4A).
      - `styleWeight` number: Style weight (0.00–1.00)
      - `weirdnessConstraint` number: Creativity / weirdness weight (0.00–1.00)
      - `audioWeight` number: Audio weight (0.00–1.00)
      - `vocalGender` 'Male' | 'Female': Vocal gender: Male or Female
      - `autoLyrics` boolean: inspo: rewrite the provided lyrics creatively
      - `variationCategory` 'subtle' | 'normal' | 'high': remaster: intensity (subtle / normal / high)
      - `stemType` string: stems: which stem to extract (e.g. lead_vocal, backing_vocals, drum_kit, bass, piano, electric_guitar). Defaults to lead_vocal.
      - `voxAudioId` string: Deprecated and ignored: a persona is now created straight from the track (voice with sourceTaskId), no vox extraction needed.
      - `durationS` number: fade-in / fade-out: fade duration in seconds
      - `speed` number: adjust-speed: speed multiplier (0.25–4)
      - `keepPitch` boolean: adjust-speed: keep the original pitch (defaults to true)
      - `sourceTaskIds` string[]: mashup: exactly 2 prior suno generation ids (taskIds) to remix together
      - `audioIds` string[]: mashup: parallel array to sourceTaskIds selecting the track in each source by its audioId (as returned in output.tracks[].audioId); omit an entry to use that source's first track
  - `webhook` string: Webhook for result

## Response `200`

Success - Request completed successfully

- CreateGenerationResponseDto
  - `code` number, required: HTTP status code
  - `data` GenerationResponseData, required
    - `taskId` string, required: Generation task ID
    - `status` 'not_started' | 'processing' | 'finished' | 'failed' | 'expired', required: Current generation status
    - `createdAt` string, required: Generation creation timestamp

## Other responses

- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment Required - Insufficient account balance
- `500`: Internal Server Error - Server error occurred

---

[API](https://skmtc.dev/api-stock/apis/api-stock-api.md) · [All operations](https://skmtc.dev/api-stock/apis/api-stock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/api-stock/apis/api-stock-api/revisions/f71e13198386?raw)