Saltar para o conteúdo principal
POST

Autorizações

string
obrigatório
Todos os endpoints requerem autenticação por Bearer TokenObtenha sua chave de API:Acesse a página de gerenciamento de chaves de API para obter sua chave de APIInclua-a no cabeçalho da requisição:

Body

string
padrão:"mai-image-2.7"
obrigatório
Nome do modelo de geração de imagensOs dois modelos têm exatamente os mesmos recursos e parâmetros.
boolean
padrão:"false"
Define se o conteúdo deve ser moderado antes do envio da tarefa de imagem.
  • true: verificar prompts e imagens de entrada com omni-moderation-latest
  • false ou omitido: não enviar solicitação de moderação, sem custo nem latência adicionais de moderação (padrão)
string
obrigatório
Descrição textual da imagem a ser gerada ou instrução de edição
  • Suporta chinês e inglês, descrições detalhadas são recomendadas
  • Até 20.000 caracteres; acima disso retorna 400
  • Não pode ser vazio nem conter apenas espaços em branco
integer
padrão:"1"
Número de imagens a serem geradasValor: 1
Apenas 1 imagem por requisição; para várias imagens, envie tarefas separadas. Valores 0, negativos ou maiores que 1 retornam 400
string
padrão:"1:1"
Proporção da imagem ou dimensões em pixels, válido apenas para texto para imagemAceita dois formatos:
  • Proporção: qualquer razão de inteiros entre 1:4 e 4:1, como 1:1, 16:9, 9:16, 21:9; combinada com resolution, define os pixels reais
  • Dimensões em pixels: larguraxaltura (também aceita largura*altura e largura×altura), como 2048x1152; nesse caso, resolution é ignorado
Limites para dimensões em pixels:
  • Largura e altura ≥ 768
  • Largura × altura ≤ 4.194.304 (2048×2048)
  • Largura e altura são arredondadas para baixo, cada uma, para um múltiplo de 32; por exemplo, 1000x1000 gera 992x992
Exemplos: ✅ 2048x2048, 2048x1152, 2560x1536; ❌ 512x512 (lado menor que 768), 2080x2048 (excede o total de pixels)
auto não é suportado; enviá-lo retorna 400
string
padrão:"1K"
Nível de resolução de saída, válido apenas quando size é uma proporçãoOpções: 1K / 2K (também aceita minúsculas)Mapeamento size × resolution → pixels reais:
4K não é suportado; outros níveis retornam 400. Como o lado menor deve ter pelo menos 768, proporções mais alongadas que 2:1 ultrapassam cerca de 1 milhão de pixels no nível 1K.
integer
Largura exata em pixels, obrigatoriamente junto com height
  • Tem a maior prioridade: quando enviados, substituem size e resolution
  • Mesmos limites das dimensões em pixels de size: largura e altura ≥ 768, total de pixels ≤ 4.194.304
  • Válido apenas para texto para imagem
integer
Altura exata em pixels, obrigatoriamente junto com width, com os mesmos limites de width
array
Array de imagens de referência; quando fornecido, ativa o modo imagem para imagem
  • 1 imagem para edição individual, várias imagens para composição
string
Tipo de fundoOpções: auto / opaque, com o mesmo efeito de omitir o parâmetro
O fundo transparente (transparent) ainda não está disponível; enviar transparent ou outros valores retorna 400
auto_aspect_ratio: true e web_grounding: true não são suportados e retornam 400. quality, style, output_format, response_format e mask_url não são suportados e são ignorados. A saída é sempre PNG.

Exemplos de uso

Texto para imagem (requisição mínima) Padrão 1:1 + 1K, saída de 1024×1024.
Texto para imagem (com proporção + 2K)
Texto para imagem (pixels exatos)
Edição individual
Composição de várias imagens (URL + base64 combinados)

Response

integer
Código de status da resposta
array
Array de dados da resposta

Consulta de resultados da tarefa

Após o envio bem-sucedido, um task_id é retornado. Consulte o status da tarefa via GET /v1/tasks/{task_id}; veja API de consulta de tarefas para mais detalhes. Recomendamos consultar a cada 3–5 segundos, com tempo limite total de 3 minutos.

Exemplo de resposta de sucesso

Acesso à imagem: data.result.images[0].url[0]. O link da imagem expira após expires_at; faça o download e salve-a o quanto antes.

Status da tarefa