kreatorflow-ai Lip Sync API

openapi: 3.2.0
info:
  title: Kreatorflow Ai Lip Sync API
  version: '2026-06-10'
  contact:
    name: KreatorFlow
    url: https://kreatorflow.ai/developers
    email: harry@kreatorflow.ai
  termsOfService: https://kreatorflow.ai/terms
  description: 'Operations tagged Lip Sync across 2 of this provider''s published API definitions: developers.kreatorflow.ai-openapi.json, kreatorflow-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://kreatorflow.ai
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Lip Sync
paths:
  /v1/lip-sync:
    post:
      operationId: postLipSync
      summary: 'Create a Lip Sync job (OmniHuman 2.0): one photo plus one voice track becomes a…'
      description: 'Create a Lip Sync job (OmniHuman 2.0): one photo plus one voice track becomes a video of that person speaking it. Paid accounts only. Priced per started second of audio. Returns a job to poll with GET /v1/jobs/{job_id}. Required scope: videos:create. Rate limit: 20 per 60 seconds per account.'
      tags:
      - Lip Sync
      x-required-scope: videos:create
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LipSyncRequest'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/CreateJobResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientBalance'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://kreatorflow.ai
      description: Production
components:
  responses:
    RateLimited:
      description: Too many requests in the window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait.
    BadRequest:
      description: 'Invalid request. prompt_required: No prompt (or text for speech) was sent. prompt_too_long: The prompt is over the model''s limit. model_not_found: Unknown model alias. duration_not_supported: The model doesn''t offer that length. aspect_ratio_not_supported: The model doesn''t offer that aspect ratio. resolution_not_supported: The model doesn''t offer that resolution. reference_combination_not_supported: These references can''t be combined, e.g. start/end frames with reference images. upload_invalid: The upload request is missing a field or has a bad type. video_edit_model_not_supported: Video edits need a Seedance 2.0 family model (2.0, Fast or Mini). video_edit_source_required: A video edit needs a source clip. voice_required: Speech needs a voice. audio_reference_too_long: The audio references add up to more than the model accepts in total (15 s on Seedance 2.0, 30 s on 2.5). Nothing was charged. audio_too_short: The voice track is under 4 seconds. Nothing was charged. audio_too_long: The voice track is over 5 minutes. Nothing was charged. audio_unreadable: The audio couldn''t be read. Nothing was charged.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientBalance:
      description: 'Not enough tokens for the quoted cost; top up and retry. insufficient_balance: Not enough tokens for the quoted cost.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing, wrong or revoked API key. invalid_api_key: The key is missing, wrong or revoked.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: Bearer challenge (on /v1/mcp).
    Forbidden:
      description: 'Not allowed. account_not_active: The developer account is suspended. scope_missing: The key lacks the scope this endpoint needs. paid_account_required: Lip Sync needs a paid account. Nothing was charged.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: Send the same key when retrying a create and you get the original job back instead of a second one.
  schemas:
    LipSyncRequest:
      type: object
      properties:
        image_upload_id:
          type: string
          description: 'string required; the photo of the person who speaks: an IMAGE upload_id from POST /v1/uploads (one clearly visible face works best); imageUploadId also accepted'
        audio_upload_id:
          type: string
          description: 'string required unless audio_job_id is sent; the voice track: an audio upload_id from POST /v1/uploads (MP3 or WAV, 4 seconds to 5 minutes, 15 MB max); audioUploadId also accepted'
        audio_job_id:
          type: string
          description: string required unless audio_upload_id is sent; the id of a completed POST /v1/audio job of the same account, used as the voice track; audioJobId also accepted
        face_consent:
          type: boolean
          description: 'boolean optional: true records your own confirmation that you are the person in the photo or have their permission. Your acceptance of the Terms and Acceptable Use Policy covers it either way. Recorded with the job'
        prompt:
          type: string
          description: string optional, max 2000 chars; direction for expression, gestures or camera
        resolution:
          type: string
          description: string optional; 720p (default) or 1080p
        webhook_url:
          type: string
          format: uri
          description: https url optional; receives terminal job callbacks
        callback_url:
          type: string
          description: alias for webhook_url
        idempotency_key:
          type: string
          description: string optional body fallback; prefer Idempotency-Key header
      required:
      - image_upload_id
      additionalProperties: true
    Error:
      type: object
      required:
      - success
      - code
      - error
      properties:
        success:
          type: boolean
          const: false
        code:
          type: string
          description: Machine-readable error code.
          enum:
          - account_not_active
          - aspect_ratio_not_supported
          - audio_reference_too_long
          - audio_too_long
          - audio_too_short
          - audio_unreadable
          - audio_upload_not_found
          - character_not_found
          - character_pending
          - character_reference_limit_exceeded
          - character_reference_unusable
          - character_reference_upload_required
          - character_registration_failed
          - character_trusted_asset_failed
          - dispatch_disabled
          - duration_not_supported
          - face_consent_required
          - generation_dispatch_failed
          - generation_dispatch_missing
          - generation_failed
          - generation_output_missing
          - generation_poll_failed
          - generation_rejected
          - generation_timeout
          - generation_unavailable
          - image_rejected
          - image_upload_not_found
          - insufficient_balance
          - internal_error
          - invalid_api_key
          - job_not_found
          - model_not_found
          - paid_account_required
          - paid_check_unavailable
          - prompt_required
          - prompt_too_long
          - rate_limited
          - reference_asset_failed
          - reference_asset_pending
          - reference_combination_not_supported
          - reference_rejected
          - reference_upload_invalid
          - reference_upload_not_found
          - reference_upload_unusable
          - resolution_not_supported
          - response_format_not_supported
          - schema_missing
          - scope_missing
          - storage_not_configured
          - upload_id_invalid
          - upload_in_use
          - upload_invalid
          - upload_not_found
          - upload_state_error
          - upload_too_large
          - video_edit_model_not_supported
          - video_edit_source_must_be_video
          - video_edit_source_not_found
          - video_edit_source_required
          - voice_not_found
          - voice_required
        error:
          type: string
          description: Human-readable message.
      additionalProperties: true
    CreateJobResult:
      type: object
      properties:
        job:
          type: string
          description: accepted job object; image/character dispatch can continue asynchronously, while video create attempts KreatorFlow dispatch before returning
        balance_tokens:
          type: number
          description: number current developer token balance after reservation or replay
        quoted_token_cost:
          type: number
          description: number token quote for the submitted request
        estimated_token_cost:
          type: number
          description: number compatibility alias for quoted_token_cost
        idempotent_replay:
          type: boolean
          description: boolean optional; true when the same Idempotency-Key returned an existing job instead of creating or dispatching another one
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your KreatorFlow API key (kf_...) as a bearer token. Keep it on your server.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Authorization header.
externalDocs:
  description: Developer docs
  url: https://developers.kreatorflow.ai/?section=docs
x-refined-from:
- developers.kreatorflow.ai-openapi.json
- kreatorflow-ai-openapi.json
x-job-error-codes:
- code: reference_rejected
  meaning: A reference did not pass screening.
- code: reference_asset_pending
  meaning: A new reference is still being reviewed.
- code: reference_asset_failed
  meaning: The reference did not pass review.
- code: generation_rejected
  meaning: The request was declined (prompt, reference or options).
- code: generation_timeout
  meaning: The job ran out of time after automatic retries.
- code: generation_unavailable
  meaning: The model is temporarily unavailable.
- code: generation_failed
  meaning: The generation failed.