Documentación de la API para quitar fondo

Descripción

Esta API en la nube usa detección inteligente de objetos destacados (SOD) para ofrecer eliminación automática y precisa de fondos. Consulta la documentación siguiente para conocer el rendimiento y la integración. Para una velocidad óptima, recomendamos que la imagen de origen pese menos de 5 MB.

🥥 Notas importantes

Conservación de datos: las URL de las imágenes generadas y los mates alfa (máscaras) solo son válidos durante 1 día. Descárgalos y guárdalos cuanto antes para evitar pérdidas.
Límites de solicitudes: el límite predeterminado de este endpoint es 2 QPS (consultas por segundo). Si necesitas mayor concurrencia o volumen, contacta al equipo comercial.

Historial de versiones

4.0 | Fecha de lanzamiento: 2025-03-20
4.0.1 | Fecha de lanzamiento: 2026-07-01 (Se agregó compatibilidad con varios resultados)

Requisitos de la imagen de entrada

Formato de imagen	Resolución	Tamaño del archivo
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	Hasta 10 MB, inclusive

🥥 Notas importantes

Las URL de salida vencen después de 24 horas.
El límite predeterminado es 2 QPS. Contáctanos para aumentar los límites de concurrencia.

URL de solicitud

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

Métodos de solicitud y ejemplos

# Crear tarea

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'

# Consultar tarea

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}'

Autenticación y permisos

Debes solicitar una clave API antes de usar estos servicios. Para saber cómo obtenerla, contacta a nuestro equipo comercial.
Autenticación de la API: pasa el token secreto mediante el Header HTTP. Para validar al solicitante y evitar el robo de credenciales, protege y guarda tu clave API de forma segura.

Construir la solicitud

1、Eliminación del fondo de la imagen

POST /api/v1/segment/submit

Parámetros de solicitud:

Nombre del parámetro	Tipo	Valor predeterminado	Valores opcionales	Descripción
image_url	String	None	-	URL de la imagen a la que se quitará el fondo (mutuamente excluyente con image_file).
image_file	String($binary)	None	-	Archivo local al que se quitará el fondo (mutuamente excluyente con image_url).
rsz_w	int	None	Integer between [0~4096]	Si es mayor que 0, la imagen devuelta se escala proporcionalmente al ancho indicado (rsz_w).
rsz_h	int	None	Integer between [0~4096]	Si es mayor que 0, la imagen devuelta se escala proporcionalmente al alto indicado (rsz_h).
crop_object	int	None	0、1	Al establecerlo en 1, se recorta la imagen al área del sujeto principal.
multi_result	int	None	0、1	Indica si se devolverán varios resultados de recorte. Nota: la facturación se calcula según la cantidad de resultados devueltos. Por ejemplo, 3 resultados consumen 3 tareas de recorte. La cantidad real depende de la predicción del modelo y normalmente es menor o igual a 5.
sync	int	0	0、1	Indica si se activa el modo síncrono. 0, modo asíncrono: la API devuelve task_id de inmediato sin esperar; después debes consultar el resultado mediante task_info. 1, modo síncrono: la API espera a que termine la eliminación del fondo antes de devolver el resultado.
output_type	int	1	1、2、3	Devuelve imagen y máscara. 1 Devuelve solo la imagen resultante. 2 Devuelve la imagen resultante y la máscara. 3 Devuelve solo la máscara.
output_format	String	png	jpeg、png	Formato de la imagen devuelta. png: fondo transparente. jpeg: fondo blanco predeterminado, no transparente. Para indicar otro color, usa el parámetro bg_color.
bg_color	String	None	Hexadecimal color string starting with "#"	Define un color de fondo sólido. Solo funciona cuando output_format es jpeg. Ejemplos: “#FFFFFF”, “#000000”, etc.
output_mask_format	String	jpeg	jpeg、png	Formato de la imagen de máscara devuelta.
timeout	int	10	1-60	Tiempo máximo, en segundos, que la API esperará el procesamiento. Solo funciona cuando sync=1 (modo síncrono).

Nota: si se establecen rsz_w y rsz_h, la imagen se ajustará a esas dimensiones sin conservar la proporción original. Cuando crop_object está activado, tampoco se conserva la proporción de la imagen original.

# Ejemplo de respuesta en modo asíncrono (sync=0)

JSON|

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

# Ejemplo de respuesta en modo síncrono (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、Eliminación del fondo de la imagen

POST /api/v1/segment/submit

Parámetros de solicitud:

# Ejemplo de respuesta en modo asíncrono (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"
}

Nombre del parámetro	Tipo	Descripción
result_cnt	Number	Cantidad de resultados devueltos (cuando multi_result=1).

Nombre del parámetro	Tipo	Valor predeterminado	Valores opcionales	Descripción
task_id	String	None	Valid Task ID	task_id devuelto por la API de eliminación de fondo (limitado al modo asíncrono con sync=0).

3、Consulta del cupo de uso

GET /api/v1/segment/quota

Parámetros de solicitud: Ninguno

# Ejemplo de respuesta

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 respuesta

Nombre del parámetro	Tipo	Descripción
image	String	URL de la imagen después de quitar el fondo.
mask	String($binary)	URL de la imagen de máscara.
results	Array	Arreglo de resultados (cuando multi_result=1).
result_cnt	Number	Cantidad de resultados devueltos (cuando multi_result=1).
status	String	data.status, estado de la tarea: 2 Completada 1 Procesando -1 Fallida -2 Tiempo agotado
used_tasks	Number	Cantidad de tareas de recorte utilizadas.
remaining_tasks	Number	Cantidad de tareas de recorte disponibles.

Códigos de estado

Códigos de estado de respuesta HTTP

Código de estado HTTP	Descripción
200	Solicitud completada correctamente.
400	Error en los parámetros del cliente. Comprueba que no falten parámetros y que sus valores sean correctos.
401	Falló la autenticación. Comprueba que X-API-KEY sea correcta y que el servicio esté activo.
404	La URL o el recurso solicitado no existe. Comprueba la URL o el ID de tarea incluido en ella.
412	Falló la validación de la URL o del archivo de imagen cargado. Comprueba la URL o el archivo.
413	El archivo cargado supera el límite de tamaño. Comprueba el tamaño y el máximo permitido por el servicio.
429	La frecuencia de solicitudes supera el límite QPS (2 de forma predeterminada). Reduce la frecuencia o contacta a soporte comercial para aumentarlo.
500	Excepción del servidor. Comunícala al equipo comercial o al soporte técnico.