> ## 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. # 创建视频生成任务 > 创建异步视频生成任务。生成方式根据必填提示词、帧图片和带类型的参考素材推断。 ## OpenAPI ````yaml /openapi.zh.json post /openapi/v1/videos/generations openapi: 3.0.3 info: title: Neural4D API description: API v1 用于上传可复用的输入文件、异步创建视频并查询任务状态和结果。 version: 1.0.0 servers: - url: https://api.neural4d.com description: 生产环境 security: - bearerAuth: [] tags: - name: 视频生成 description: 创建异步视频生成任务。 - name: 任务 description: 通过 ID 查询异步任务。 - name: 文件 description: 上传可在生成请求中复用的输入文件。 paths: /openapi/v1/videos/generations: post: tags: - 视频生成 summary: 创建视频生成任务 description: 创建异步视频生成任务。生成方式根据必填提示词、帧图片和带类型的参考素材推断。 operationId: createVideoGeneration parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoGenerationJsonRequest' examples: text_to_video: summary: 通过文本生成视频 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: 使用已上传的首帧图片生成视频 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: 使用首尾帧图片生成视频 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: 使用参考素材生成视频 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: 已接受生成任务 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: 生产环境 components: schemas: VideoGenerationJsonRequest: type: object required: - model - prompt additionalProperties: false properties: output_with_audio: type: boolean description: 是否随视频生成原生音频。 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: 视频生成模型标识。参数默认值和可选值取决于所选模型。 prompt: type: string minLength: 1 description: 描述待生成视频内容的必填文本提示词。 maxLength: 1000 'n': type: integer minimum: 1 maximum: 4 default: 1 description: 需要创建的视频生成任务数量。 resolution: type: string enum: - 480p - 720p - 1080p - 4K example: 720p description: 所选视频模型允许的分辨率。 aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' - '2:3' - '3:2' example: '16:9' description: 所选视频模型允许的宽高比。 frame_images: type: array minItems: 1 maxItems: 2 items: $ref: '#/components/schemas/VideoFrameImage' description: >- 通过 POST /openapi/v1/files 上传的首帧和尾帧图片，支持 JPG、JPEG、PNG 和 WEBP 格式。每个 frame_type 最多出现一次，每项都必须提供 file_id。 input_references: type: array minItems: 1 maxItems: 12 items: $ref: '#/components/schemas/VideoInputReference' description: >- 已上传的图片、视频和音频参考素材。图片支持 JPG、JPEG、PNG 和 WEBP，视频支持 MP4 和 MOV，音频支持 MP3 和 WAV。接口最多接受六张图片、四个视频和两个音频。单个音频时长为 2 至 15 秒且不超过 15 MB，所有音频总时长不超过 15 秒。音频必须与至少一个图片或视频同时使用。下游请求体不得超过 64 MB；大文件不要使用 Base64 编码。每项声明媒体类型，并且必须提供 file_id。 duration: type: integer minimum: 1 description: 所选视频模型允许的时长，单位为秒。 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: 生成请求返回的批次任务 ID。 data: type: array minItems: 1 items: $ref: '#/components/schemas/TaskReceipt' description: 本次请求创建的生成结果子项。 usage: $ref: '#/components/schemas/TaskUsage' description: 可用时返回本次提交任务扣除的总点数。 status: allOf: - $ref: '#/components/schemas/TaskStatus' description: 本次提交的视频任务的当前状态。 created_at: type: integer format: int64 description: 批次任务创建时间的 Unix 时间戳，单位为秒。 mode: type: string enum: - text_to_video - first_frame_image_to_video - first_last_frame_image_to_video - reference_to_video description: 本次提交任务使用的视频生成模式。 model: type: string enum: - bytedance/seedance-2.0 - bytedance/seedance-2.0-fast - google/veo-3.1 - xai/grok-imagine description: 本次提交任务使用的视频生成模型。 VideoFrameImage: type: object required: - type - frame_type - file_id additionalProperties: false properties: type: type: string enum: - image description: 帧素材的媒体类型，固定为 image。 frame_type: type: string enum: - first_frame - last_frame description: 此图片表示的帧位置：first_frame 或 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: 文件上传接口返回的文件 ID。帧图片支持 JPG、JPEG、PNG 和 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: 一个带媒体类型的图片、视频或音频参考素材，使用文件上传接口返回的文件 ID。 Seedance20VideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: 是否随视频生成原生音频。Seedance 2.0 默认开启。 default: true model: type: string enum: - bytedance/seedance-2.0 description: 视频生成模型标识。参数默认值和可选值取决于所选模型。 resolution: type: string enum: - 480p - 720p - 1080p - 4K default: 720p description: 所选视频模型允许的分辨率。 aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' default: '16:9' description: 所选视频模型允许的宽高比。 duration: type: integer minimum: 4 maximum: 15 enum: - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 default: 5 description: 所选视频模型允许的时长，单位为秒。 Seedance20FastVideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: 是否随视频生成原生音频。Seedance 2.0 Fast 默认开启。 default: true model: type: string enum: - bytedance/seedance-2.0-fast description: 视频生成模型标识。参数默认值和可选值取决于所选模型。 resolution: type: string enum: - 480p - 720p default: 720p description: 所选视频模型允许的分辨率。 aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' default: '16:9' description: 所选视频模型允许的宽高比。 duration: type: integer minimum: 4 maximum: 15 enum: - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 default: 5 description: 所选视频模型允许的时长，单位为秒。 Veo31VideoParameters: type: object required: - model properties: output_with_audio: type: boolean description: 是否随视频生成原生音频。Veo 3.1 默认开启。 default: true model: type: string enum: - google/veo-3.1 description: 视频生成模型标识。参数默认值和可选值取决于所选模型。 resolution: type: string enum: - 720p - 1080p - 4K default: 720p description: 所选视频模型允许的分辨率。 aspect_ratio: type: string enum: - '16:9' - '9:16' default: '16:9' description: 所选视频模型允许的宽高比。 duration: type: integer minimum: 4 maximum: 8 enum: - 4 - 5 - 6 - 7 - 8 default: 8 description: 所选视频模型允许的时长，单位为秒。 GrokImagineVideoParameters: type: object required: - model not: required: - output_with_audio properties: model: type: string enum: - xai/grok-imagine description: 视频生成模型标识。参数默认值和可选值取决于所选模型。 resolution: type: string enum: - 480p - 720p default: 720p description: 所选视频模型允许的分辨率。 aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' - '2:3' - '3:2' default: '16:9' description: 所选视频模型允许的宽高比。 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: 所选视频模型允许的时长，单位为秒。 TaskReceipt: type: object required: - uuid - status - created_at properties: uuid: type: string description: 生成结果子项 UUID。 format: uuid status: allOf: - $ref: '#/components/schemas/TaskStatus' description: 标准化后的任务生命周期状态。 created_at: type: integer format: int64 description: Unix 时间戳（秒）。 updated_at: type: integer format: int64 description: Unix 时间戳（秒）。 usage: $ref: '#/components/schemas/TaskUsage' description: 可用时返回此任务扣除的点数。 error: allOf: - $ref: '#/components/schemas/TaskError' description: 任务失败时返回的错误详情。 TaskUsage: type: object required: - credits properties: credits: type: number format: float minimum: 0 description: 该任务或请求扣除的点数。 example: 26 TaskStatus: type: string enum: - queued - processing - succeeded - failed description: 异步任务的标准化生命周期状态。 ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ApiError' description: 结构化错误详情。 VideoImageReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - image description: 此参考素材的媒体类型，固定为 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: 文件上传接口返回的文件 ID。图片参考素材支持 JPG、JPEG、PNG 和 WEBP 格式。 VideoVideoReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - video description: 此参考素材的媒体类型，固定为 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: 文件上传接口返回的文件 ID。视频参考素材支持 MP4 和 MOV 格式。 VideoAudioReference: type: object required: - type - file_id additionalProperties: false properties: type: type: string enum: - audio description: 此参考素材的媒体类型，固定为 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: 文件上传接口返回的文件 ID。音频参考素材支持 MP3 和 WAV 格式，单个文件时长为 2 至 15 秒且不超过 15 MB。 TaskError: type: object required: - code - message description: 异步处理记录的失败详情。 properties: code: type: string description: 稳定且可供程序读取的任务失败代码。 message: type: string description: 便于阅读的任务失败说明。 failed_at: type: integer format: int64 description: 任务失败时的 Unix 时间戳（秒）。 retryable: type: boolean description: 重试相同操作是否可能成功。 ApiError: type: object required: - code - message properties: code: type: string description: 稳定且可供程序读取的错误码。 example: invalid_prompt message: type: string example: prompt is required and must be a non-empty string description: 便于阅读的错误说明。 doc_url: type: string format: uri nullable: true example: https://api.neural4d.com/docs/errors#invalid_prompt description: 包含此错误更多信息的可选文档 URL。 headers: RateLimitLimitRequests: description: 当前时间窗口的请求上限。 schema: type: integer format: int32 minimum: 0 RateLimitRemainingRequests: description: 当前时间窗口内的剩余请求次数。 schema: type: integer format: int32 minimum: 0 RateLimitResetRequests: description: 请求时间窗口距离重置的时长，例如 1s。 schema: type: string example: 1s RetryAfter: description: 重试前需要等待的秒数。 schema: type: integer minimum: 0 responses: BadRequest: description: 请求无效 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: 提示词无效 value: error: code: invalid_prompt message: prompt is required and must be a non-empty string unsupported_model: summary: 模型不受支持 value: error: code: unsupported_model message: 'Unsupported modelKey: missing-model' model_unavailable: summary: 模型不可用 value: error: code: model_unavailable message: 'Model is unavailable: veo-3.1' Unauthorized: description: 认证失败 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: 当前已认证用户无权访问该资源或点数不足 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: 已超过请求或配额限制 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: 内部或上游服务错误 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: 使用 Bearer 方式发送的 Neural4D API 密钥。 x-default: ${YOUR_API_KEY} ````