Skip to main content
Ferramentas criativas

Referência da API de conclusão de remoção de imagem

Este documento detalha os parâmetros do modelo de conclusão de remoção de imagem. Esse modelo remove um ou mais elementos de uma imagem, como pessoas, animais de estimação, objetos, texto ou marcas d'água, preservando o plano de fundo. Especifique as áreas a remover usando uma imagem de máscara.

Guia relacionado: Conclusão de remoção de imagem
  • Este documento se aplica apenas à região China (Beijing). Para usar o modelo, utilize uma chave de API da região China (Beijing).
  • O modelo image-erase-completion está disponível atualmente apenas como avaliação gratuita. Após esgotar sua cota gratuita, não será mais possível chamar o modelo, pois opções pagas não são suportadas. Como alternativas, recomendamos o uso de Edição de imagem - Qwen ou Edição de imagem - Wan2.1.

Pré-requisitos

Obter uma chave de API e exportar a chave de API como uma variável de ambiente.

Chamada HTTP

Para reduzir tempos de espera e evitar timeouts de requisição, o serviço processa as solicitações de forma assíncrona. São necessárias duas requisições:
  • Crie uma tarefa: Envie uma requisição para criar uma tarefa de geração de imagem. Essa requisição retorna um ID de tarefa.
  • Consultar o resultado pelo ID da tarefa: Utilize o ID da tarefa retornado para consultar o resultado.

Etapa 1: Crie uma tarefa

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Cabeçalhos da requisição

  • Conclusão de remoção de imagem
curl --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "image-erase-completion",
    "input": {
            "image_url": "http://xxx/input.png",
            "mask_url": "http://xxx/mask.png",
            "foreground_url": "http://xxx/foreground.png"
        },
    "parameters":{
        "dilate_flag":true
    }
}'
Content-TypestringObrigatórioTipo de conteúdo da requisição. O valor deve ser application/json.
AuthorizationstringObrigatórioRecomendamos usar sua chave de API do Model Studio. Também é possível utilizar sua chave de API do DashScope. Exemplo: Bearer d1xxx2a.
X-DashScope-AsyncstringObrigatórioDefine se o processamento assíncrono deve ser ativado. Defina este parâmetro como enable.

Corpo da requisição

modelstringObrigatórioModelo a ser chamado.
inputobjectObrigatórioDetalhes da imagem de entrada, como a URL da imagem.

Propriedades

image_urlstringObrigatórioURL ou dados codificados em Base64 da imagem de entrada.A URL deve ser publicamente acessível e usar HTTP ou HTTPS.Requisitos da imagem:
  • Formatos: JPEG, PNG, JPG, BMP, WEBP.
  • Resolução: Mínimo de 512×512 pixels e máximo de 4096×4096 pixels.
  • Intervalo de lado: [512, 4096] pixels.
  • Tamanho do arquivo: Não deve exceder 10 MB.
  • A URL não deve conter caracteres chineses.
mask_urlstringObrigatórioURL ou dados codificados em Base64 da imagem de máscara que especifica a área a remover.A URL deve ser publicamente acessível e usar HTTP ou HTTPS.Requisitos da imagem:
  • Formatos: JPG, JPEG, PNG, HEIF, WEBP.
  • Resolução: Mínimo de 512×512 pixels e máximo de 4096×4096 pixels.
  • Intervalo de lado: [512, 4096] pixels.
  • Tamanho do arquivo: Não deve exceder 10 MB.
Para criar uma máscara, pinte em uma tela em branco com o mesmo tamanho da imagem de entrada. Áreas com valores de pixel diferentes de zero servem como máscara de remoção. Alternativamente, use a segmentação de instância humana para gerar diretamente um resultado de segmentação como máscara de remoção.foreground_urlstring OpcionalURL ou dados codificados em Base64 da imagem de máscara que especifica a área a preservar.A URL deve ser publicamente acessível e usar HTTP ou HTTPS.Requisitos da imagem:
  • Formatos: JPG, JPEG, PNG, HEIF, WEBP.
  • Resolução: Mínimo de 512×512 pixels e máximo de 4096×4096 pixels.
  • Intervalo de lado: [512, 4096] pixels.
  • Tamanho do arquivo: Não deve exceder 10 MB.
Para criar uma máscara de preservação, pinte em uma tela em branco com o mesmo tamanho da imagem de entrada. Áreas com valores de pixel diferentes de zero servem como máscara de preservação. Alternativamente, use a segmentação de instância humana para especificar um ID de pessoa, isolando a área de máscara dessa pessoa para evitar que ela seja removida.
parametersobject OpcionalParâmetros para processamento de imagem.

Propriedades

fast_modeboolOpcionalDefine se o modo rápido deve ser ativado. O valor padrão é false. No modo rápido, a inferência leva cerca de um quarto do tempo do modo padrão. Este modo é adequado para cenários que não exigem alto nível de detalhe.dilate_flagboolOpcionalO valor padrão é true. Recomendamos definir como true se um algoritmo gerar a máscara de remoção e como false se você pintar manualmente a máscara de remoção.add_watermark booleanOpcionalAdiciona uma marca d'água Generated by AI. O valor padrão é true, o que adiciona a marca d'água ao canto inferior esquerdo da imagem de saída.

Resposta 

{
    "output": {
        "task_status": "PENDING",
        "task_id": "53950fb7-281a-4e60-b543-xxxxxxxxxxxx"
    },
    "request_id": "1027557e-8c3f-9db5-8cd2-xxxxxxxxxxxx"
}
outputobjectDetalhes da saída da tarefa.

Propriedades

task_idstringIdentificador exclusivo da tarefa.task_statusstringStatus da tarefa.
  • PENDING: A tarefa está na fila.
  • RUNNING: A tarefa está em andamento.
  • SUSPENDED: A tarefa está suspensa.
  • SUCCEEDED: A tarefa foi concluída com êxito.
  • FAILED: A tarefa falhou.
codestringCódigo de erro. Este parâmetro não é retornado se a requisição for bem-sucedida.
messagestringMensagem de erro. Este parâmetro não é retornado se a requisição for bem-sucedida.
request_idstringID exclusivo da requisição. Use este ID para rastrear e solucionar problemas.

Etapa 2: Consultar o resultado

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Cabeçalhos da requisição

  • Resultado da tarefa
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/53950fb7-281a-4e60-b543-xxxxxxxxxxxx
AuthorizationstringObrigatórioSua chave de API. Exemplo: Bearer d1**2a.

Parâmetros de caminho

task_idstringObrigatórioID da tarefa.

Resposta

  • Tarefa concluída
  • Tarefa em andamento
  • Tarefa com falha
Os resultados de tarefas concluídas ficam disponíveis por 24 horas. Após esse período, o sistema exclui a tarefa e seus resultados. A URL da imagem gerada também expira após 24 horas; portanto, salve a imagem logo após recuperar o resultado da tarefa.
{
    "request_id": "b67df059-ca6a-9d51-afcd-9b3c4456b1e2",
    "output": {
        "task_id": "53950fb7-281a-4e60-b543-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2024-05-16 13:50:01.247",
        "scheduled_time": "2024-05-16 13:50:01.354",
        "end_time": "2024-05-16 13:50:27.795",
        "output_image_url": "http://xxx/result.png"
    },
    "usage": {
        "image_count": 1
    }
}
outputobjectDetalhes da saída da tarefa.

Propriedades

task_id stringID da tarefa.task_status stringStatus da tarefa.
  • PENDING: A tarefa está na fila.
  • RUNNING: A tarefa está em andamento.
  • SUSPENDED: A tarefa está suspensa.
  • SUCCEEDED: A tarefa foi concluída com êxito.
  • FAILED: A tarefa falhou.
task_metrics objectEstatísticas da tarefa.

Propriedades

TOTAL integerNúmero total de tarefas.SUCCEEDED integerNúmero de tarefas bem-sucedidas.FAILED integerNúmero de tarefas com falha.
submit_time stringHorário em que a tarefa foi enviada.scheduled_time stringHorário em que a tarefa começou a ser executada.end_time stringHorário em que a tarefa foi concluída.output_image_url stringURL da imagem de saída.codestringCódigo de erro. Este parâmetro não é retornado se a requisição for bem-sucedida.messagestringMensagem de erro. Este parâmetro não é retornado se a requisição for bem-sucedida.
usageobjectEstatísticas de uso.

Propriedades

image_countintegerNúmero de imagens geradas.
request_idstringID exclusivo da requisição. Use este ID para rastrear e solucionar problemas.

Códigos de status

Para códigos de status comuns dos serviços do Model Studio, consulte Mensagens de erro. Esta API também retorna os seguintes códigos de status específicos:

Código de status HTTP

Código de erro

Mensagem de erro

Descrição

400

InvalidParameter.JsonPhrase

input json error

JSON inválido na requisição.

400

InvalidParameter.FileDownload

oss download error

Falha ao baixar a imagem de entrada.

400

InvalidParameter.ImageFormat

read image error

Falha ao ler a imagem.

400

InvalidParameter.ImageContent

The image content is not compliant.

O conteúdo da imagem não está em conformidade.

400

InvalidParameter

An input parameter value is out of range: xxx

Um valor de parâmetro de entrada está fora do intervalo.

400

InvalidParameter.ImageResolution

The input image size is too small or too large.

O tamanho da imagem de entrada é muito pequeno ou muito grande.

500

InternalError.Algo

algorithm process error

Erro de algoritmo.

500

InternalError.FileUpload

oss upload error

Falha ao carregar o arquivo.

Uso da API
Referência da API de Geração de Texto
Geração de Imagens
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais