> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Asset Upload Batch > Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch). ## OpenAPI ````yaml /openapi/external-api.json post /v3/assets/direct-uploads/batches openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Avatar Realtime description: >- Low-latency streaming avatar sessions — create a stream, poll for its HLS URL, push text, consume per-word timestamps - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos paths: /v3/assets/direct-uploads/batches: post: tags: - Asset Batches summary: Create Asset Upload Batch description: >- Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch). operationId: createAssetUploadBatchV3 parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAssetUploadBatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateAssetUploadBatchResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: Invalid file(s) at index 3. param: files doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: authentication_failed message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateAssetUploadBatchRequest: additionalProperties: false properties: title: anyOf: - type: string - type: 'null' default: null description: Display name for the batch, shown in the HeyGen app. title: Title callback_url: anyOf: - type: string - type: 'null' default: null description: >- Reserved for parity with the other batch APIs; asset completion does not emit a webhook. title: Callback Url files: description: >- Files to presign, same shape as POST /v3/assets/direct-uploads. Max 100 per batch. items: $ref: '#/components/schemas/AssetUploadItem' maxItems: 100 minItems: 1 title: Files type: array required: - files title: CreateAssetUploadBatchRequest type: object CreateAssetUploadBatchResponse: properties: batch_id: description: >- Identifier of the created batch. Pass to POST /v3/assets/complete/batches once all files are uploaded. title: Batch Id type: string items: description: >- One presigned upload slot per requested file, in the submitted order. items: $ref: '#/components/schemas/AssetUploadBatchItem' title: Items type: array required: - batch_id - items title: CreateAssetUploadBatchResponse type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation required: - code - message AssetUploadItem: additionalProperties: false description: |- One requested file in a create-upload-batch call. Mirrors the fields ``CreateAssetUploadRequest`` (POST /v3/assets/direct-uploads) validates. properties: filename: description: >- Original filename for reference/metadata. The stored object's extension is derived from content_type. title: Filename type: string content_type: description: >- Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf'). Verified against the stored bytes when the batch is completed. title: Content Type type: string size_bytes: description: >- Exact byte size of the file. Signed into the upload URL so it cannot be exceeded. title: Size Bytes type: integer checksum_sha256: anyOf: - type: string - type: 'null' default: null description: >- Optional SHA256 of the file as hex. When provided, S3 enforces it on upload. title: Checksum Sha256 required: - filename - content_type - size_bytes title: AssetUploadItem type: object AssetUploadBatchItem: description: >- One issued presigned upload slot in the create response. Mirrors the single-upload ``CreateAssetUploadResponse`` (POST /v3/assets/direct-uploads). properties: asset_id: description: >- Reusable asset identifier. Becomes usable after POST /v3/assets/complete/batches finalizes the batch. title: Asset Id type: string upload_url: description: Presigned S3 URL. PUT the raw file bytes here. title: Upload Url type: string upload_headers: additionalProperties: type: string description: Headers that must be sent verbatim on the PUT request. title: Upload Headers type: object expires_in_seconds: description: Seconds until the upload URL expires. title: Expires In Seconds type: integer max_bytes: description: Maximum allowed upload size in bytes. title: Max Bytes type: integer status: const: pending_upload description: Upload lifecycle status. Always 'pending_upload' here. title: Status type: string required: - asset_id - upload_url - upload_headers - expires_in_seconds - max_bytes - status title: AssetUploadBatchItem type: object responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````