POST/api/v1/generate/video-imitate

Imitar movimentos

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: imitateVideo · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`Idempotency-Key`	header	não	string

Schema do request

JSON

{
  "additionalProperties": true,
  "properties": {
    "callbackUrl": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "characterImage": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "model": {
      "description": "Quando omitido, o servidor usa kling-motion-2.6.",
      "enum": [
        "kling-motion-2.6",
        "kling-motion-3.0"
      ],
      "type": "string"
    },
    "motionVideo": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "quality": {
      "description": "Quando omitido, o servidor usa 720p.",
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string"
    }
  },
  "required": [
    "characterImage",
    "motionVideo"
  ],
  "type": "object"
}

Respostas

HTTP	Significado
`202`	Geração aceita para processamento assíncrono
`default`	Erro padronizado

Geração de vídeo com controle de movimentos (Kling Motion) aplica os movimentos de um vídeo de referência a uma imagem de personagem. Responde 202 Accepted com um taskId; acompanhe o resultado por polling em GET /api/v1/tasks/:id ou via webhook.

Escopo necessário: generate:video.

Valores fixos (não configuráveis nesta API): aspectRatio 9:16. A characterImage é a imagem de referência e o motionVideo o vídeo de movimento aplicado.

Body

Campo	Tipo	Obrigatório	Valores / restrições
`characterImage`	string	sim	URL HTTPS pública da imagem do personagem (≤10 MB)
`motionVideo`	string	sim	URL HTTPS pública do vídeo de movimento (MP4, 3–30s)
`model`	string	não	`kling-motion-2.6` (default), `kling-motion-3.0`
`quality`	string	não	`720p` (default), `1080p`
`callbackUrl`	string	não	URL HTTPS para webhook de conclusão

Modelos disponíveis

Ambos aceitam os mesmos inputs (qualidades 720p/1080p, aspect 9:16); diferem no custo e na fidelidade do movimento.

Modelo	Quando usar
`kling-motion-2.6`	Padrão — estável e econômico
`kling-motion-3.0`	Mais recente, melhor fidelidade de movimento

Detecção automática de duração

A duração do motionVideo — base do custo — é detectada automaticamente a partir do arquivo. A duração precisa estar entre 3 e 30 segundos.

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/generate/video-imitate \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-imt-001" \
  -d '{
    "characterImage": "https://storage.avatrix.io/assets/avatrix-0eb6a322-1435-4730-a30f-b87dc3003ce3.jpg",
    "motionVideo": "https://storage.avatrix.io/assets/video-0b54dc80-aa35-4567-9e4d-1c97b0eb2069.mp4",
    "model": "kling-motion-2.6",
    "quality": "720p"
  }'

Resposta — 202

JSON

{ "success": true, "data": { "taskId": "...", "status": "queued" } }

O status: "queued" é só o rótulo de criação. No polling (GET /api/v1/tasks/:id) a task evolui por pending → submitted → processing → completed (com resultUrl) ou failed. Ver Ciclo de vida da task.

Idempotência

Envie o header Idempotency-Key (opcional, máx. 128 chars). Requisições repetidas com a mesma chave (24h) retornam a resposta original sem novo débito. Concorrência limitada a 20 tasks simultâneas por usuário. Ver Idempotência.

Custo

Cobrança por duração do vídeo de referêcia (em segundos), de acordo com o modelo e a qualidade (720p/1080p).

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	campos inválidos, vídeo não detectável ou fora de 3–30s
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	token sem `generate:video`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`GENERATION_FAILED`	502	falha do provider
`PROVIDER_UNAVAILABLE`	503	provider indisponível

Ver Códigos de erro e Escopos.