> ## 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. # 上传文件 > 上传一个本地图片、视频或音频文件，并返回可复用的文件 ID。 ## OpenAPI ````yaml /openapi.zh.json post /openapi/v1/files 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/files: post: tags: - 文件 summary: 上传文件 description: 上传一个本地图片、视频或音频文件，并返回可复用的文件 ID。 operationId: uploadFile parameters: [] requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateManagedFileRequest' responses: '201': description: 文件已上传 content: application/json: schema: $ref: '#/components/schemas/ManagedFile' example: id: 550e8400-e29b-41d4-a716-446655440000 filename: first-frame.png bytes: 245760 mime_type: image/png created_at: 1784044800 '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: CreateManagedFileRequest: type: object required: - file additionalProperties: false properties: file: type: string format: binary description: >- 需要上传的文件。图片支持 JPG、JPEG、PNG、GIF、WEBP、BMP、HEIC 和 HEIF；视频支持 MP4、MOV、WEBM、M4V、OGG 和 OGV；音频支持 MP3 和 WAV。 ManagedFile: type: object required: - id - filename - bytes - mime_type - created_at additionalProperties: false properties: 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。 filename: type: string example: first-frame.png description: 上传文件的原始名称。 bytes: type: integer format: int64 minimum: 0 example: 245760 description: 上传文件大小，单位为字节。 mime_type: type: string example: image/png description: 检测到的上传文件媒体类型。 created_at: type: integer format: int64 description: 文件创建时间的 Unix 时间戳，单位为秒。 ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ApiError' 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。 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 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: 使用 Bearer 方式发送的 Neural4D API 密钥。 x-default: ${YOUR_API_KEY} ````