> ## Documentation Index > Fetch the complete documentation index at: https://docs.adskull.io/llms.txt > Use this file to discover all available pages before exploring further. # Create an AI video generation job ## OpenAPI ````yaml /api/openapi.yaml post /v1/video-generations openapi: 3.1.0 info: title: AdSkull Public API version: 1.0.0 summary: Public API for AdSkull creative generation. description: > Create AI ad assets, images, videos, voiceovers, custom voices, and talking avatars. Responses expose AdSkull product resources. servers: - url: https://api.adskull.io security: - bearerAuth: [] tags: - name: Account - name: Models - name: Assets - name: Images - name: Videos - name: Voices - name: Talking Avatars - name: Webhooks - name: LLM - name: LLM OpenAI Compat - name: LLM Anthropic Compat paths: /v1/video-generations: post: tags: - Videos summary: Create an AI video generation job operationId: createVideoGeneration parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVideoGenerationRequest' responses: '202': description: Video generation accepted. content: application/json: schema: $ref: '#/components/schemas/GenerationJob' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ContentPolicyViolation' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: - videos:write components: parameters: IdempotencyKey: in: header name: Idempotency-Key required: true schema: type: string minLength: 8 maxLength: 128 description: Unique key for safe retries of job creation requests. schemas: CreateVideoGenerationRequest: type: object required: - model_id - prompt - resolution - duration_seconds description: | Video generation request. The backend validates the `(model_id, tier, resolution, duration_seconds, audio_enabled)` tuple against the pricing matrix and rejects any invalid combo with `400 invalid_request`. Call `GET /v1/models/{model_id}` for the authoritative options, or use the per-model matrix in the docs. Required-in-practice fields beyond the OpenAPI `required` list: • `mode` — must be `edit` for V2V models or `motion` for MC models. • `audio_enabled` — required boolean for any model with audio pricing rows (Veo, Sora, Wan 2.6, Wan 2.7, V2V, MC, Kling, Seedance 1.5 Pro, Seedance 2.5, Seedance 2.5 V2V). Orientation cheatsheet: • 9:16 → vertical / portrait (TikTok, Reels, Shorts) • 16:9 → horizontal / landscape (YouTube, web) • 1:1 → square (Instagram feed) Models with inherit-from-input ratios (do NOT send `ratio`): wan-2.6, hailuo-2.3, grok-imagine-1.5, wan-2.6-v2v, kling-2.6-mc, kling-3.0-mc. minimax-h3 inherits only on the image-to-video path: send `ratio` for text-to-video, omit it when input_image_url is set (the output matches the input image). Image-to-video-only models (input_image_url REQUIRED): wan-2.6, hailuo-2.3, grok-imagine-1.5. properties: mode: type: string enum: - generate - edit - motion description: > • generate — text or first-frame image-to-video (most models). • edit — required for wan-2.6-v2v, wan-2.7-videoedit, seedance-2.5-v2v, minimax-h3-v2v (needs input_video_url). • motion — required for kling-2.6-mc, kling-3.0-mc (needs input_image_url + input_video_url). model_id: type: string enum: - veo-3.1 - kling-2.6 - kling-3.0 - seedance-1.5-pro - seedance-2.0 - seedance-2.5 - wan-2.6 - wan-2.7 - hailuo-2.3 - grok-imagine - grok-imagine-1.5 - happyhorse-1.1 - kling-3.0-turbo - gemini-omni - sora-2 - sora-2-pro - minimax-h3 - wan-2.6-v2v - wan-2.7-videoedit - seedance-2.5-v2v - minimax-h3-v2v - kling-2.6-mc - kling-3.0-mc description: Video model. Call GET /v1/models/{model_id} for full options. prompt: type: string minLength: 1 maxLength: 4096 tier: type: string description: > Per-model performance tier: • veo-3.1 → lite | fast | quality (default fast; lite cannot extend) • seedance-2.0 → fast | quality (fast has no 1080p) • hailuo-2.3 → standard | pro • grok-imagine → fun | normal | spicy (spicy rejects uploaded refs) Other models ignore this field. ratio: type: string description: > Aspect ratio `W:H`. Per-model supported values: • veo-3.1, sora-2, sora-2-pro → 9:16, 16:9 • kling-2.6, kling-3.0 → 9:16, 16:9, 1:1 • seedance-1.5-pro, seedance-2.0 → 1:1, 4:3, 3:4, 16:9, 9:16, 21:9 (seedance-2.0 also: adaptive) • seedance-2.5, seedance-2.5-v2v → 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive • wan-2.7, wan-2.7-videoedit → 16:9, 9:16, 1:1, 4:3, 3:4 • grok-imagine → 2:3, 3:2, 1:1, 16:9, 9:16 • minimax-h3, minimax-h3-v2v → 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 (minimax-h3-v2v also: adaptive — its default; minimax-h3 REQUIRES ratio for text-to-video but ignores it when input_image_url is set — omit it for image-to-video) DO NOT send `ratio` for wan-2.6, hailuo-2.3, wan-2.6-v2v, kling-*-mc (ratio inherits from the input media). example: '9:16' resolution: type: string description: | Per-model resolution: • veo-3.1 → 720p | 1080p | 4K • kling-2.6 → 1080p • kling-3.0 → 720p | 1080p • seedance-1.5-pro → 480p | 720p | 1080p • seedance-2.0 (tier=fast) → 480p | 720p • seedance-2.0 (tier=quality) → 480p | 720p | 1080p • seedance-2.5, seedance-2.5-v2v → 480p | 720p (no 1080p, no 4K) • wan-2.6, wan-2.7, wan-2.6-v2v, wan-2.7-videoedit → 720p | 1080p • hailuo-2.3 → 768p (6/10s) | 1080p (6s only) • minimax-h3, minimax-h3-v2v → 768p | 2K • grok-imagine → 480p | 720p • sora-2 → 720p • sora-2-pro → 720p | 1024x1792 | 1080x1920 duration_seconds: type: string description: | Duration as a STRING (not number). Per-model accepted values: • veo-3.1 → "8" (8s; extend for more) • kling-2.6 → "5" | "10" • kling-3.0 → "3" | "5" | "7" | "10" | "15" • seedance-1.5-pro → "4" | "8" | "12" • seedance-2.0 → "4" | "8" | "12" • seedance-2.5, seedance-2.5-v2v → "4" | "5" | "8" | "10" | "15" | "20" | "30" • wan-2.6 → "5" | "10" | "15" • wan-2.7 → "5" | "8" • wan-2.7-videoedit → "5" | "8" | "10" • wan-2.6-v2v → "5" | "10" • hailuo-2.3 (768p) → "6" | "10" • hailuo-2.3 (1080p) → "6" only • minimax-h3, minimax-h3-v2v → "4"–"15" (every integer) • grok-imagine → "6" | "10" | "15" | "20" | "30" • sora-2 / sora-2-pro → "4" | "8" | "12" | "16" | "20" example: '8' audio_enabled: type: boolean description: > Per-model audio behavior: • forced-on (rejects false): veo-3.1, sora-2, sora-2-pro, wan-2.6, minimax-h3, minimax-h3-v2v (native stereo audio always on) • forced-off (rejects true): wan-2.7, hailuo-2.3, grok-imagine, wan-2.6-v2v, wan-2.7-videoedit, MC • toggle: kling-2.6, kling-3.0, seedance-1.5-pro, seedance-2.5, seedance-2.5-v2v • n/a (ignored): seedance-2.0 negative_prompt: type: string description: | Content to avoid. Supported by kling, seedance, wan, V2V, MC. Ignored by veo, sora, hailuo, grok. input_image_url: type: string format: uri description: | Hosted image URL. REQUIRED for wan-2.6 / hailuo-2.3 (image-to-video) and for mode=motion (kling-*-mc). Optional first-frame for veo / kling / seedance / wan-2.7 / grok / sora. seedance-2.5 also accepts up to 4 reference images (never mixed with first/last frames). Use POST /v1/assets to host local files. input_video_url: type: string format: uri description: | Hosted video URL. REQUIRED for mode=edit (wan-2.6-v2v, wan-2.7-videoedit, seedance-2.5-v2v, minimax-h3-v2v) and mode=motion (kling-*-mc). minimax-h3-v2v references must be MP4/MOV (H.264/H.265), ≤ 50 MB, 2–15s per clip, ≤ 15s total, and are billed on input + output seconds. Use POST /v1/assets to host local files. GenerationJob: type: object required: - id - object - status - credits_reserved - created_at - assets properties: id: type: string object: type: string enum: - image_generation_job - video_generation_job - talking_avatar_job status: type: string enum: - queued - processing - completed - failed - canceled progress_percent: type: integer minimum: 0 maximum: 100 nullable: true credits_reserved: type: integer credits_used: type: integer nullable: true credits_refunded: type: integer default: 0 request: type: object additionalProperties: true assets: type: array items: $ref: '#/components/schemas/Asset' failure_code: type: string nullable: true failure_message: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true failed_at: type: string format: date-time nullable: true Asset: type: object required: - id - object - type - url - mime_type properties: id: type: string object: type: string const: asset type: type: string enum: - image - audio - video url: type: string format: uri mime_type: type: string size_bytes: type: integer duration_seconds: type: number nullable: true width: type: integer nullable: true height: type: integer nullable: true expires_at: type: string format: date-time nullable: true ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string message: type: string request_id: type: string details: type: object additionalProperties: true responses: InvalidRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' InsufficientCredits: description: Not enough credits. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: Missing scope, plan, or resource access. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: Idempotency or concurrency conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' ContentPolicyViolation: description: Input content is not allowed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Rate limit exceeded. headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key ````