> ## Documentation Index > Fetch the complete documentation index at: https://docs.neural4d.com/llms.txt > Use this file to discover all available pages before exploring further. # Create video generation tasks > Creates asynchronous video generation tasks. Generation behavior is inferred from the required prompt, frame images, and typed reference assets. ## OpenAPI ````yaml /openapi.json post /openapi/v1/videos/generations openapi: 3.0.3 info: title: Neural4D API description: >- API v1 uploads reusable input files, creates videos asynchronously, and retrieves task status and results. version: 1.0.0 servers: - url: https://api.neural4d.com description: Production server security: - bearerAuth: [] tags: - name: Video generation description: Create asynchronous video generation tasks. - name: Tasks description: Poll asynchronous tasks by ID. - name: Files description: Upload input files for reuse in generation requests. paths: /openapi/v1/videos/generations: post: tags: - Video generation summary: Create video generation tasks description: >- Creates asynchronous video generation tasks. Generation behavior is inferred from the required prompt, frame images, and typed reference assets. operationId: createVideoGeneration parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoGenerationJsonRequest' examples: text_to_video: summary: Generate a video from text value: model: xai/grok-imagine prompt: A cinematic tracking shot through a neon-lit street at night duration: 6 'n': 1 resolution: 720p aspect_ratio: '16:9' first_frame_image_to_video: summary: Animate an uploaded first-frame image value: model: bytedance/seedance-2.0 prompt: The camera slowly pushes in while soft wind moves the leaves frame_images: - type: image frame_type: first_frame file_id: 550e8400-e29b-41d4-a716-446655440000 duration: 5 'n': 1 resolution: 720p aspect_ratio: '16:9' output_with_audio: true first_last_frame_image_to_video: summary: Animate first and last frames value: model: bytedance/seedance-2.0-fast prompt: Move naturally from the opening frame to the closing frame frame_images: - type: image frame_type: first_frame file_id: 550e8400-e29b-41d4-a716-446655440000 - type: image frame_type: last_frame file_id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 duration: 5 'n': 1 resolution: 720p aspect_ratio: '16:9' output_with_audio: true reference_to_video: summary: Generate from reference assets value: model: google/veo-3.1 prompt: >- Create a cohesive cinematic sequence using the supplied references input_references: - type: image file_id: 550e8400-e29b-41d4-a716-446655440000 - type: video file_id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - type: audio file_id: 7d1fa4bb-41e6-4a5d-88d8-1851f5342e87 duration: 8 'n': 1 resolution: 720p aspect_ratio: '16:9' output_with_audio: true responses: '202': description: Generation tasks accepted headers: x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/TaskList' example: id: normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d status: queued created_at: 1784044800 mode: text_to_video model: xai/grok-imagine data: - uuid: 7d1fa4bb-41e6-4a5d-88d8-1851f5342e87 status: queued created_at: 1784044800 usage: credits: 90 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' servers: - url: https://api.neural4d.com description: Production server components: schemas: VideoGenerationJsonRequest: type: object required: - model - prompt additionalProperties: false properties: output_with_audio: type: boolean description: Whether to generate native audio with the video. model: type: string enum: - bytedance/seedance-2.0 - bytedance/seedance-2.0-fast - google/veo-3.1 - xai/grok-imagine example: bytedance/seedance-2.0 description: >- Video generation model identifier. Parameter defaults and allowed values depend on the selected model. prompt: type: string minLength: 1 description: Required text instruction describing the video to generate. maxLength: 1000 'n': type: integer minimum: 1 maximum: 4 default: 1 description: Number of video generation tasks to create. resolution: type: string enum: - 480p - 720p - 1080p - 4K example: 720p description: Resolution allowed by the selected video model. aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' - '2:3' - '3:2' example: '16:9' description: Aspect ratio allowed by the selected video model. frame_images: type: array minItems: 1 maxItems: 2 items: $ref: '#/components/schemas/VideoFrameImage' description: >- First-frame and last-frame images uploaded through POST /openapi/v1/files. Supported formats are JPG, JPEG, PNG, and WEBP. Each frame_type may appear at most once, and every item requires file_id. input_references: type: array minItems: 1 maxItems: 12 items: $ref: '#/components/schemas/VideoInputReference' description: >- Uploaded image, video, and audio reference assets. Images support JPG, JPEG, PNG, and WEBP; videos support MP4 and MOV; audio supports MP3 and WAV. The endpoint accepts up to six images, four videos, and two audio files. Each audio file must be 2 to 15 seconds and no larger than 15 MB, and the combined audio duration must not exceed 15 seconds. Audio must be accompanied by at least one image or video. The downstream request body must not exceed 64 MB; do not Base64-encode large files. Every item declares its media type and requires file_id. duration: type: integer minimum: 1 description: Duration allowed by the selected video model, in seconds. allOf: - oneOf: - $ref: '#/components/schemas/Seedance20VideoParameters' - $ref: '#/components/schemas/Seedance20FastVideoParameters' - $ref: '#/components/schemas/Veo31VideoParameters' - $ref: '#/components/schemas/GrokImagineVideoParameters' discriminator: propertyName: model mapping: bytedance/seedance-2.0: $ref: '#/components/schemas/Seedance20VideoParameters' bytedance/seedance-2.0-fast: $ref: '#/components/schemas/Seedance20FastVideoParameters' google/veo-3.1: $ref: '#/components/schemas/Veo31VideoParameters' xai/grok-imagine: $ref: '#/components/schemas/GrokImagineVideoParameters' TaskList: type: object required: - id - status - created_at - mode - model - data properties: id: type: string example: normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d description: Batch task ID returned by the generation request. data: type: array minItems: 1 items: $ref: '#/components/schemas/TaskReceipt' description: Generated child items created by the request. usage: $ref: '#/components/schemas/TaskUsage' description: Total credits charged for the submitted tasks when available. status: allOf: - $ref: '#/components/schemas/TaskStatus' description: Current status shared by the submitted video tasks. created_at: type: integer format: int64 description: Unix timestamp in seconds when the batch task was created. mode: type: string enum: - text_to_video - first_frame_image_to_video - first_last_frame_image_to_video - reference_to_video description: Video generation mode shared by the submitted tasks. model: type: string enum: - bytedance/seedance-2.0 - bytedance/seedance-2.0-fast - google/veo-3.1 - xai/grok-imagine description: Video generation model used by the submitted tasks. VideoFrameImage: type: object required: - type - frame_type - file_id additionalProperties: false properties: type: type: string enum: - image description: Media type of the frame asset. Always image. frame_type: type: string enum: - first_frame - last_frame description: 'Position represented by this image: first_frame or last_frame.' file_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 description: >- File ID returned by the file upload endpoint. Supported formats for frame images: JPG, JPEG, PNG, and WEBP. VideoInputReference: oneOf: - $ref: '#/components/schemas/VideoImageReference' - $ref: '#/components/schemas/VideoVideoReference' - $ref: '#/components/schemas/VideoAudioReference' discriminator: propertyName: type mapping: image: $ref: '#/components/schemas/VideoImageReference' video: $ref: '#/components/schemas/VideoVideoReference' audio: $ref: '#/components/schemas/VideoAudioReference' description: >- One typed image, video, or audio reference using a file ID returned by the file upload endpoint. Seedance20VideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: >- Whether to generate native audio with the video. Enabled by default for Seedance 2.0. default: true model: type: string enum: - bytedance/seedance-2.0 description: >- Video generation model identifier. Parameter defaults and allowed values depend on the selected model. resolution: type: string enum: - 480p - 720p - 1080p - 4K default: 720p description: Resolution allowed by the selected video model. aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' default: '16:9' description: Aspect ratio allowed by the selected video model. duration: type: integer minimum: 4 maximum: 15 enum: - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 default: 5 description: Duration allowed by the selected video model, in seconds. Seedance20FastVideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: >- Whether to generate native audio with the video. Enabled by default for Seedance 2.0 Fast. default: true model: type: string enum: - bytedance/seedance-2.0-fast description: >- Video generation model identifier. Parameter defaults and allowed values depend on the selected model. resolution: type: string enum: - 480p - 720p default: 720p description: Resolution allowed by the selected video model. aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' default: '16:9' description: Aspect ratio allowed by the selected video model. duration: type: integer minimum: 4 maximum: 15 enum: - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 default: 5 description: Duration allowed by the selected video model, in seconds. Veo31VideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: >- Whether to generate native audio with the video. Enabled by default for Veo 3.1. default: true model: type: string enum: - google/veo-3.1 description: >- Video generation model identifier. Parameter defaults and allowed values depend on the selected model. resolution: type: string enum: - 720p - 1080p - 4K default: 720p description: Resolution allowed by the selected video model. aspect_ratio: type: string enum: - '16:9' - '9:16' default: '16:9' description: Aspect ratio allowed by the selected video model. duration: type: integer minimum: 4 maximum: 8 enum: - 4 - 5 - 6 - 7 - 8 default: 8 description: Duration allowed by the selected video model, in seconds. GrokImagineVideoParameters: type: object required: - model not: required: - output_with_audio properties: model: type: string enum: - xai/grok-imagine description: >- Video generation model identifier. Parameter defaults and allowed values depend on the selected model. resolution: type: string enum: - 480p - 720p default: 720p description: Resolution allowed by the selected video model. aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '2:3' - '3:2' default: '16:9' description: Aspect ratio allowed by the selected video model. duration: type: integer minimum: 6 maximum: 30 enum: - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - 16 - 17 - 18 - 19 - 20 - 21 - 22 - 23 - 24 - 25 - 26 - 27 - 28 - 29 - 30 default: 6 description: Duration allowed by the selected video model, in seconds. TaskReceipt: type: object required: - uuid - status - created_at properties: uuid: type: string description: Generated child item UUID. format: uuid status: allOf: - $ref: '#/components/schemas/TaskStatus' description: Normalized task lifecycle status. created_at: type: integer format: int64 description: Unix timestamp in seconds. updated_at: type: integer format: int64 description: Unix timestamp in seconds. usage: $ref: '#/components/schemas/TaskUsage' description: Credits charged for this task when available. error: allOf: - $ref: '#/components/schemas/TaskError' description: Error details when the task fails. TaskUsage: type: object required: - credits properties: credits: type: number format: float minimum: 0 description: Credits charged for the task or submission. example: 26 TaskStatus: type: string enum: - queued - processing - succeeded - failed description: Normalized lifecycle status of an asynchronous task. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ApiError' description: Structured error details. VideoImageReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - image description: Media type of this reference. Always image. file_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 description: >- File ID returned by the file upload endpoint. Supported image reference formats: JPG, JPEG, PNG, and WEBP. VideoVideoReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - video description: Media type of this reference. Always video. file_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 description: >- File ID returned by the file upload endpoint. Supported video reference formats: MP4 and MOV. VideoAudioReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - audio description: Media type of this reference. Always audio. file_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 description: >- File ID returned by the file upload endpoint. Supported audio reference formats: MP3 and WAV. Each file must be 2 to 15 seconds and no larger than 15 MB. TaskError: type: object required: - code - message description: Failure details recorded by asynchronous processing. properties: code: type: string description: Stable machine-readable task failure code. message: type: string description: Human-readable explanation of the task failure. failed_at: type: integer format: int64 description: Unix timestamp in seconds when the task failed. retryable: type: boolean description: Whether retrying the same operation may succeed. ApiError: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. example: invalid_prompt message: type: string example: prompt is required and must be a non-empty string description: Human-readable explanation of the error. doc_url: type: string format: uri nullable: true example: https://api.neural4d.com/docs/errors#invalid_prompt description: Optional documentation URL with more information about the error. headers: RateLimitLimitRequests: description: Request limit for the current window. schema: type: integer format: int32 minimum: 0 RateLimitRemainingRequests: description: Requests remaining in the current window. schema: type: integer format: int32 minimum: 0 RateLimitResetRequests: description: Time until the request window resets, such as 1s. schema: type: string example: 1s RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 responses: BadRequest: description: Invalid request headers: x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_prompt: summary: Invalid prompt value: error: code: invalid_prompt message: prompt is required and must be a non-empty string unsupported_model: summary: Unsupported model value: error: code: unsupported_model message: 'Unsupported modelKey: missing-model' model_unavailable: summary: Model unavailable value: error: code: model_unavailable message: 'Model is unavailable: veo-3.1' Unauthorized: description: Authentication failed headers: x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_api_key message: The API key is invalid or expired Forbidden: description: >- The authenticated user cannot access this resource or has insufficient credits headers: x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_credits message: Insufficient credits for video generation RateLimited: description: Request or quota limit exceeded headers: Retry-After: $ref: '#/components/headers/RetryAfter' x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests. Retry after the indicated interval. InternalError: description: Internal or upstream service error headers: x-ratelimit-limit-requests: $ref: '#/components/headers/RateLimitLimitRequests' x-ratelimit-remaining-requests: $ref: '#/components/headers/RateLimitRemainingRequests' x-ratelimit-reset-requests: $ref: '#/components/headers/RateLimitResetRequests' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: An internal error occurred securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: Neural4D API key using the Bearer scheme. x-default: ${YOUR_API_KEY} ````