Darkvi
Entrar
Imagens

Gerar imagem

Cria um prompt de geração de imagem e inicia o processamento assíncrono. A geração é feita por um worker externo; use GET /api/v1/images/:id para acompanhar o status e obter a URL assinada quando status=DONE.

POSThttps://darkvi.com/api/v1/images

Autenticação

Envie sua chave de API no cabeçalho Authorization. Token gerado em darkvi.com/settings. O token deve pertencer a um usuário ativo.

Cabeçalho
Authorization: Bearer <SEU_TOKEN_DE_API>

Parâmetros

Corpo (JSON)

  • promptstringobrigatório

    Descrição da imagem a ser gerada. Máximo: 1000 caracteres.

    Exemplo: Um dragão voando sobre montanhas nevadas ao pôr do sol, estilo fotorrealista
  • aspectstringopcional

    Proporção da imagem. Valores aceitos: "16:9" (paisagem) ou "9:16" (retrato/shorts). Omitir para proporção padrão.

    Exemplo: 16:9
  • referencePathstringopcional

    Key da imagem de referência (obtida em POST /api/v1/images/reference). Requer plano pago ou ADMIN. Formato esperado: reference_image/<uuid>.webp.

    Exemplo: reference_image/550e8400-e29b-41d4-a716-446655440000.webp

Exemplo de requisição

JSON
{
  "prompt": "Um dragão voando sobre montanhas nevadas ao pôr do sol, estilo fotorrealista",
  "aspect": "16:9",
  "referencePath": "reference_image/550e8400-e29b-41d4-a716-446655440000.webp"
}

Respostas

201 CreatedPrompt aceito e encaminhado para o worker. Faça polling em GET /api/v1/images/:id até status=DONE.
Resposta
{
  "success": true,
  "id": 4821,
  "status": "PENDING",
  "remaining": 14,
  "limit": 100
}

Observações

  • Geração é assíncrona: o registro é criado com status PENDING e processado em background.
  • Ciclo de status: PENDING → PROCESSING → GENERATING → DONE (ou ERROR).
  • Limites diários por tier: ADMIN=200, planos padrão=100, planos 8/30=20.
  • Burst limit: 5 gerações/minuto (ADMINs: 20/minuto). Compartilhado com o painel web.
  • A URL da imagem gerada só está disponível quando status=DONE (campo url em GET :id).
  • Para usar imagem de referência: primeiro faça POST /api/v1/images/reference (multipart/form-data, campo 'file') e passe a 'key' retornada como referencePath. Requer plano pago ou ADMIN (plano 8 retorna 403).