Documentação API de remoção de fundo

Descrição

Esta nuvem API usa detecção inteligente de objetos salientes (SOD) para remoção de fundo automatizada e de alta precisão. Mantenha as imagens de origem abaixo de 5 MB para velocidade ideal.

🥥 Notas importantes

Retenção de dados: A imagem de saída URLs e os mates alfa (máscaras) são válidos por apenas 1 dia. Baixe e armazene-os imediatamente.
Limites de taxa: o limite padrão é 2 QPS. Entre em contato com vendas ou desenvolvimento de negócios para obter maior simultaneidade.

Histórico de versões

4.0 | Data de lançamento: 2025-03-20
4.0.1 | Data de lançamento: 2026-07-01 (Adicionado suporte para saídas com vários resultados)

Requisitos de imagem de entrada

Formato de imagem	Resolução	Tamanho do arquivo
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	Até 10 MB (inclusive)

🥥 Notas importantes

A saída URLs expira após 24 horas.
O limite de taxa padrão é 2 QPS. Entre em contato conosco para atualizar os limites de simultaneidade.

Solicitar URL

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

Métodos e exemplos de solicitação

# Criar tarefa

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# Buscar tarefa

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

Autenticação e permissões

Solicite um API Key antes de usar esses serviços. Entre em contato com o desenvolvimento de negócios ou vendas para obter detalhes.
Autenticação API: Passe seu token secreto através do HTTP Header e armazene seu API Key com segurança.

Solicitação de construção

1、Remoção de fundo de imagem

POST /api/v1/segment/submit

Parâmetros de solicitação:

Nome do parâmetro	Tipo	Valor padrão	Valores opcionais	Descrição
image_url	String	None	-	URL da imagem da qual remover o fundo (mutuamente exclusivo com image_file).
image_file	String($binary)	None	-	Arquivo de imagem local (mutuamente exclusivo com image_url).
rsz_w	int	None	Integer between [0~4096]	Se for maior que 0, dimensione a imagem retornada proporcionalmente a rsz_w.
rsz_h	int	None	Integer between [0~4096]	Se for maior que 0, dimensione a imagem retornada proporcionalmente a rsz_h.
crop_object	int	None	0、1	Defina como 1 para cortar a área de assunto principal.
multi_result	int	None	0、1	Se deve retornar vários resultados de fosqueamento. A cobrança é baseada na contagem de resultados retornados, normalmente não superior a 5.
sync	int	0	0、1	0 retorna task_id imediatamente para pesquisa task_info posterior; 1 aguarda a conclusão e retorna o resultado.
output_type	int	1	1、2、3	Retornar resultados de imagem e máscara. 1 Somente imagem. 2 Imagem e máscara. 3 Somente máscara.
output_format	String	png	jpeg、png	Formato de imagem retornado. png: fundo transparente. jpeg: fundo branco por padrão; use bg_color para outra cor.
bg_color	String	None	Hexadecimal color string starting with "#"	Cor de fundo sólida, efetiva apenas quando output_format é jpeg. Exemplos: "#FFFFFF", "#000000".
output_mask_format	String	jpeg	jpeg、png	Formato de imagem de máscara retornado.
timeout	int	10	1-60	Tempo limite de espera de processamento de API em segundos, efetivo somente quando sync=1.

Nota: Definir as escalas rsz_w e rsz_h para essas dimensões sem preservar a proporção. crop_object também não preserva a proporção original.

# Exemplo de resposta para o modo Async (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# Exemplo de resposta para modo de sincronização (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、Remoção de fundo de imagem

POST /api/v1/segment/submit

Parâmetros de solicitação:

# Exemplo de resposta para o modo Async (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

Nome do parâmetro	Tipo	Descrição
result_cnt	Number	Número de resultados retornados quando multi_result=1

Nome do parâmetro	Tipo	Valor padrão	Valores opcionais	Descrição
task_id	String	None	Valid Task ID	task_id retornado pela remoção de fundo API, para o modo async com sync=0.

3、Consulta de cota de uso

GET /api/v1/segment/quota

Parâmetros de solicitação: Nenhum

# Exemplo de resposta

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

Parâmetros de resposta

Nome do parâmetro	Tipo	Descrição
image	String	URL da imagem após remoção do fundo
mask	String($binary)	URL da imagem da máscara
results	Array	Matriz de resultados quando multi_result=1
result_cnt	Number	Número de resultados retornados quando multi_result=1
status	String	Status da tarefa data.status: 2 Concluído 1 Processamento -1 Falha -2 Tempo limite esgotado
used_tasks	Number	Número de tarefas de fosqueamento usadas
remaining_tasks	Number	Número de tarefas de fosqueamento disponíveis restantes

Códigos de status

Códigos de status de resposta HTTP

Código de status de resposta HTTP	Descrição
200	Solicitação bem-sucedida.
400	Erro de parâmetro do cliente. Verifique valores ausentes ou inválidos.
401	Falha na autenticação. Verifique X-API-KEY e ativação do serviço.
404	URL solicitado ou o recurso não existe.
412	Imagem URL carregada ou falha na validação do arquivo.
413	O arquivo enviado excede o limite de tamanho.
429	A frequência de solicitação excede o limite QPS. Diminua a velocidade ou entre em contato com o suporte comercial.
500	Exceção do servidor. Entre em contato com o suporte comercial ou técnico.