Skip to main content
POST
Gere uma imagem para a conta conectada. Usa a mesma cota de mídia e as mesmas proteções do aplicativo web. Salve o generationId retornado e use images_download para recuperar a imagem. Reutilize requestId ao tentar novamente a mesma requisição.

Autenticação e permissões

string
obrigatório
Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são aceitos apenas pelo MCP, não por este endpoint REST.
Permissões necessárias: images:write. É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.

Parâmetros

string
Opcional na camada de transporte: o servidor insere um identificador antes da validação quando ele é omitido. Forneça seu próprio UUID v4 estável para recuperar com segurança uma resposta perdida.Formato: “uuid”. Padrão: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
string
obrigatório
Valor de texto.Comprimento mínimo: 10. Comprimento máximo: 1200.
string
Valor de texto.Valores aceitos: “square”, “landscape”, “portrait”. Valor padrão: “square”.
string
Uma chave de objeto JPG, PNG ou WebP enviado em uploads/{yourUserId}/. URLs remotas não são aceitas.Comprimento mínimo: 1. Comprimento máximo: 512.
O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.

Idempotência

Use um UUID v4 em requestId ou no cabeçalho HTTP Idempotency-Key para cada alteração. Reutilize o mesmo identificador e argumentos idênticos após uma falha de rede. Se ambos forem fornecidos, devem ser iguais. Repetir uma requisição salva não repete a operação nem consome outra chamada mensal. Requisições com falha ou interrompidas não são reiniciadas automaticamente. Qualquer alteração pode retornar HTTP 202 quando uma nova tentativa encontra a mesma requisição ainda em execução, mesmo que a primeira execução normalmente seja síncrona. Se a execução foi concluída, mas resultStored é false, uma nova tentativa retorna HTTP 200 com o estado salvo da requisição em vez do resultado original. Recupere a saída pela ação de histórico, resultado ou download do domínio correspondente.

Exemplos de requisição

Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.

Resposta

Esta operação retorna HTTP 202 enquanto está em execução. Salve requestId e consulte action_request_get com esse identificador e o nome da operação original. Os estados de consulta são running, completed, failed e interrupted. Um resultado concluído pode apontar para um processamento de mídia separado; continue com a ação de status ou de saída específica da operação. Metadados finais da geração retornados pelo handler após o término da geração da imagem. Não são incluídos bytes de imagem, previewDataUrl nem URL de download.

Campos do resultado

Recuperar e consultar esta requisição

Use o mesmo identificador mesmo após perder a conexão. Se resultStored for false, recupere a saída pela ação correspondente de histórico, resultado ou download. Nunca inicie uma segunda geração apenas para verificar o progresso.
HTTP 200

Notas da operação

  • Exige images:write. Espaços nas extremidades do prompt são removidos, e ele deve conter 10–1200 caracteres; ele também é normalizado antes da geração. aspectRatio tem square como padrão e também aceita landscape ou portrait. É aceito no máximo um referenceImageKey.
  • Esta é uma ação de longa duração. A resposta inicial da API/MCP normalmente informa running; consulte periodicamente action_request_get com operation images_generate e o mesmo requestId para obter o resultado final mostrado aqui.
  • Usa a cota diária normal de geração de imagens da conta. As imagens geradas da conta expiram sete dias após a criação; baixe o resultado antes de expiresAt.
  • Esta ação usa as criações e os envios do próprio usuário conectado, inclusive quando a credencial está conectada em um contexto de equipe.
  • As chaves de referência devem apontar para envios concluídos em uploads/{yourUserId}/ e terminar em .jpg, .jpeg, .png ou .webp. URLs remotas, chaves de outros usuários, segmentos de travessia de diretórios, barras invertidas, escapes percentuais, strings de consulta, fragmentos e caracteres de controle são rejeitados.
  • Cada referência deve ser não vazia, ter no máximo 8 MiB (8,388,608 bytes), ser decodificada como o tipo de imagem identificado pela extensão e medir 128–4096 pixels de cada lado. A contagem de pixels decodificados também é limitada. Uma referência enviada continua reutilizável; essas ações de geração não consomem nem excluem o arquivo enviado.
  • Use um requestId UUID v4 ou o cabeçalho HTTP Idempotency-Key e reutilize-o com entradas idênticas ao tentar novamente. A camada de integração registra cada alteração e retorna seu estado ou resultado registrado sem executá-la novamente. Uma requisição com falha ou interrompida não é repetida automaticamente.
  • Somente uma imagem pode ser gerada por vez para este usuário. Use images_list e images_get para inspecionar o estado de criação e images_download para obter os bytes PNG. O identificador da geração é uma string opaca; não o substitua por requestId.

Uso

Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.

Erros