/green/image/asyncscan e /green/image/results - AI Guardrails: Central de Documentação do Alibaba Cloud

Envie tarefas de moderação assíncrona de imagens e consulte os resultados. Use /green/image/asyncscan para moderar imagens em busca de pornografia, terrorismo e conteúdo politicamente sensível, violações de anúncios, QR codes, cenas indesejáveis e logotipos. Após enviar as tarefas, use /green/image/results para consultar os resultados periodicamente ou configure uma URL de callback para recebê-los automaticamente.

/green/image/asyncscan

Envia uma ou mais imagens para moderação assíncrona. Os resultados não são retornados imediatamente — obtenha-os consultando /green/image/results periodicamente ou configurando uma URL de callback.

Para construir a solicitação HTTP, consulte Estrutura da solicitação e Visão geral do SDK.

Faturamento

Cobrança por chamada. Para detalhes sobre preços, consulte a documentação de faturamento do Content Moderation.

Tempo limite de resposta

O tempo máximo de resposta para uma solicitação de moderação síncrona é de 6 segundos. Se a moderação não for concluída nesse período, o sistema retornará um erro de tempo limite. Caso não precise dos resultados em tempo real, utilize solicitações de moderação assíncrona. Ao chamar operações de moderação síncrona, defina o tempo limite como 6 segundos.

Cenários de moderação

Cenário	Valor de scenes**	Rótulos de resultado
Detecção de pornografia	`porn`	`normal`, `sexy`, `porn`
Detecção de terrorismo e conteúdo politicamente sensível	`terrorism`	`normal`, `bloody`, `explosion`, `outfit`, `logo`, `weapon`, `politics`, `violence`, `crowd`, `parade`, `carcrash`, `flag`, `location`, `drug`, `gamble`, `others`
Detecção de violação de anúncio	`ad`	`normal`, `ad`, `politics`, `porn`, `abuse`, `terrorism`, `contraband`, `spam`, `npx`, `qrcode`, `programCode`
Detecção de QR code	`qrcode`	`normal`, `qrcode`, `programCode`
Detecção de cena indesejável	`live`	`normal`, `meaningless`, `PIP`, `smoking`, `drivelive`, `drug`, `gamble`
Detecção de logotipo	`logo`	`normal`, `TV`, `Trademark`

É possível especificar vários cenários em uma única solicitação. Nesse caso, cada cenário é cobrado separadamente.

Nota

Para detecção de violação de anúncio e QR code, configure os rótulos de detecção de acordo com seu caso de uso. Consulte Personalizar políticas para moderação assistida por máquina.

Limite de QPS

50 chamadas por segundo por conta. Exceder esse limite aciona o throttling.

Requisitos de imagem

Formato de URL: HTTP ou HTTPS
Formatos suportados: PNG, JPG, JPEG, BMP, GIF, WEBP
Tamanho máximo: 20 MB
Tempo limite de download: 3 segundos. Imagens que não puderem ser baixadas dentro de 3 segundos retornam um erro de tempo limite.
Resolução mínima: 256 × 256 pixels (recomendado para melhor precisão na moderação)
Armazenamento: Utilize o Object Storage Service (OSS) ou Content Delivery Network (CDN) para garantir a disponibilidade confiável das imagens.

Recuperação de resultados

Os resultados da moderação ficam retidos por até 1 hora (ou 24 horas se offline estiver definido como true). Existem duas opções de recuperação:

Notificação por callback: Defina o parâmetro callback ao enviar as tarefas. O Content Moderation envia os resultados via POST para sua URL à medida que são concluídos.
Consulta periódica: Chame /green/image/results após enviar as tarefas. Faça consultas em intervalos de 30 segundos.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`bizType`	String	Não	`default`	O cenário de negócios. Crie e gerencie cenários no Content Moderation console. Consulte Personalizar políticas para moderação assistida por máquina.
`scenes`	StringArray	Sim	`["porn"]`	Os cenários de moderação. Valores válidos: `porn`, `terrorism`, `ad`, `qrcode`, `live`, `logo`. Especifique múltiplos cenários como um array: `["porn","terrorism"]`.
`callback`	String	Não	`http://www.example.com/callback`	A URL de callback para receber os resultados da moderação. Deve suportar HTTP POST, codificação UTF-8 e aceitar os parâmetros `checksum` e `content`. Se não for definida, consulte `/green/image/results` periodicamente para obter os resultados.
`seed`	String	Não	`abc_123`	Uma string aleatória usada para gerar a assinatura do callback. Até 64 caracteres: letras, dígitos e sublinhados. Obrigatório quando `callback` estiver definido.
`cryptType`	String	Não	`SHA256`	O algoritmo de criptografia para notificações de callback. Valores válidos: `SHA256` (HMAC-SHA256, padrão), `SM3` (HMAC-SM3, retorna uma string hexadecimal em minúsculas; por exemplo, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 é retornado após criptografar abc usando o algoritmo HMAC-SM3).
`offline`	Boolean	Não	`false`	O modo de moderação. `true`: modo nearline — as tarefas são enfileiradas e iniciadas dentro de 24 horas. `false`: modo em tempo real (padrão) — solicitações além do limite de concorrência são rejeitadas.
`tasks`	JSONArray	Sim	—	A lista de imagens para moderar. Até 100 elementos por solicitação. Para enviar 100 objetos de uma vez, aumente o limite de concorrência relevante para um valor superior a 100. Consulte parâmetros da tarefa.

Parâmetros da tarefa

Cada elemento em tasks utiliza a seguinte estrutura:

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`dataId`	String	Não	`img-001`	O ID do objeto de moderação. Até 128 caracteres: letras, dígitos, hifens (`-`), sublinhados (`_`) e pontos (`.`). Retornado na resposta para correlacionar os resultados aos seus dados.
`url`	String	Sim	`https://example.com/image.png`	A URL da imagem. Deve ser HTTP ou HTTPS e publicamente acessível. Até 2.048 caracteres.
`clientInfo`	JSONObject	Não	`{"userId":"123","userNick":"Alice"}`	Informações do cliente. Substitui o parâmetro global `clientInfo` quando definido. Consulte Parâmetros comuns.
`extras`	JSONObject	Não	—	Parâmetros adicionais. Não obrigatórios para moderação de imagens.
`interval`	Integer	Não	`2`	O intervalo de captura de quadros para imagens GIF e imagens longas. Um quadro é capturado a cada `interval` quadros. Deve ser usado com `maxFrames`. Por padrão, apenas o primeiro quadro é moderado.
`maxFrames`	Integer	Não	`20`	O número máximo de quadros a serem capturados de uma imagem GIF ou imagem longa. Padrão: `1`. Se `interval × maxFrames` for menor que a contagem total de quadros, o intervalo será ajustado automaticamente.

Lógica de quadros para GIF e imagens longas:

Todos os exemplos abaixo usam interval e maxFrames juntos — ambos os parâmetros são obrigatórios.

Imagens GIF: Tratadas como um array de quadros. Um quadro é capturado por interval quadros.
Imagens verticais longas (altura > 400 px e proporção altura/largura > 2,5): Contagem de quadros = ⌈altura ÷ largura⌉.
Imagens horizontais longas (largura > 400 px e proporção largura/altura > 2,5): Contagem de quadros = ⌈largura ÷ altura⌉.

A taxa é baseada no número real de quadros moderados.

Parâmetros de resposta

Parâmetro	Tipo	Exemplo	Descrição
`code`	Integer	`200`	O código de status HTTP. Consulte Códigos de erro comuns.
`msg`	String	`OK`	A mensagem de resposta.
`dataId`	String	`img-001`	O ID do objeto de moderação, ecoado da solicitação.
`taskId`	String	`fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695`	O ID da tarefa de moderação. Use-o para consultar resultados via `/green/image/results`.
`url`	String	`https://example.com/image.png`	A URL da imagem, ecoada da solicitação. Até 2.048 caracteres.

Formato da notificação de callback

Quando o Content Moderation envia resultados para sua URL de callback, ele inclui dois parâmetros:

checksum: Um hash SHA-256 de UID + Seed + Content, onde UID é o ID da sua conta Alibaba Cloud. Verifique esse valor no seu servidor para detectar adulterações.
content: Uma string codificada em JSON. Analise-a usando o mesmo formato da resposta de sucesso de /green/image/results.

Nota

UID deve ser um ID de conta Alibaba Cloud, não um ID de usuário RAM.

Se o seu servidor retornar HTTP 200, a notificação será considerada entregue. Caso contrário, o Content Moderation tentará reenviar a notificação até 16 vezes. Após 16 tentativas falhas, a notificação é descartada — verifique sua URL de callback se parar de receber resultados.

Exemplo

Solicitação:

http(s)://[Endpoint]/green/image/asyncscan
&<Common request parameters>

{
    "scenes": ["porn"],
    "tasks": [
        {
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "url": "https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

Resposta:

{
    "code": 200,
    "msg": "OK",
    "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

/green/image/results

Consulta os resultados de tarefas de moderação assíncrona de imagens enviadas via /green/image/asyncscan.

Para construir a solicitação HTTP, consulte Estrutura da solicitação e Visão geral do SDK.

Faturamento

Gratuito.

Notas de uso

Consulte os resultados 30 segundos após enviar uma tarefa.
Os IDs de tarefa expiram com base na configuração offline:
- offline=false (padrão): ID de tarefa válido por 1 hora
- offline=true: ID de tarefa válido por 24 horas

Limite de QPS

50 chamadas por segundo por conta. Exceder esse limite aciona o throttling.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`body`	JSONArray	Sim	`["fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]`	A lista de IDs de tarefa a serem consultados. Até 100 elementos. Obtenha os IDs de tarefa na resposta de `/green/image/asyncscan`.

Parâmetros de resposta

Parâmetro	Tipo	Exemplo	Descrição
`code`	Integer	`200`	O código de status HTTP. Consulte Códigos de erro comuns.
`msg`	String	`OK`	A mensagem de resposta.
`dataId`	String	`uuid-xxxx-xxx-1234`	O ID do objeto de moderação, ecoado da solicitação original.
`taskId`	String	`img4wlJcb7p4wH4lAP3111111-123456`	O ID da tarefa de moderação.
`url`	String	`http://www.example.com/image.jpg`	A URL da imagem. Até 2.048 caracteres.
`storedUrl`	String	`http://www.example.com/evidence`	A URL do OSS da evidência de imagem armazenada. Preenchido apenas quando o armazenamento de evidências está ativado e a imagem corresponde à regra de armazenamento.
`extras`	JSONObject	—	Informações adicionais. Para moderação de `ad`, contém `hitLibInfo` — detalhes sobre correspondências em bibliotecas de texto personalizadas. Consulte hitLibInfo.
`results`	JSONArray	—	Resultados da moderação. Contém um ou mais objetos `result` quando HTTP 200 é retornado. Consulte result.

result

Parâmetro	Tipo	Exemplo	Descrição
`scene`	String	`terrorism`	O cenário de moderação. Valores válidos: `porn`, `terrorism`, `ad`, `qrcode`, `live`, `logo`.
`label`	String	`sexy`	A categoria do resultado. Consulte Rótulos de resultado para valores por cenário.
`sublabel`	String	—	A subcategoria. Retornado apenas para os cenários `porn` e `terrorism`, e somente quando habilitado.
`suggestion`	String	`block`	A ação recomendada. Valores válidos: `pass` (nenhuma ação necessária), `review` (revisão manual necessária), `block` (violação — exclua ou restrinja conteúdo).
`rate`	Float	`91.54`	A pontuação de confiança, de `0` a `100`. Use `suggestion`, `label` e `sublabel` juntos para tomar decisões de moderação — não confie apenas em `rate`.
`frames`	JSONArray	—	URLs temporárias de quadros para imagens longas truncadas. Cada URL é válida por 5 minutos. Consulte frame.
`hintWordsInfo`	JSONArray	—	Palavras-chave de risco correspondentes na imagem. Retornado apenas para moderação de `ad`. Consulte hintWordsInfo.
`qrcodeData`	StringArray	`["http://www.example.com/01ZZOliO"]`	Conteúdo de texto extraído dos QR codes detectados. Retornado apenas para moderação de `qrcode`.
`qrcodeLocations`	JSONArray	—	Coordenadas dos QR codes detectados. Consulte qrcodeLocation.
`programCodeData`	JSONArray	—	Localização dos códigos de mini programa detectados. Retornado apenas quando a detecção de código de mini programa está habilitada. Consulte programCodeData.
`logoData`	JSONArray	—	Detalhes dos logotipos detectados. Retornado apenas para moderação de `logo`. Consulte logoData.
`sfaceData`	JSONArray	—	Detalhes dos rostos detectados em conteúdo de terrorismo. Retornado apenas para moderação de `terrorism`. Consulte sfaceData.
`ocrData`	StringArray	—	Texto completo detectado na imagem. Não retornado por padrão. Entre em contato com seu gerente de vendas para ativar este recurso.

Rótulos de resultado

Detecção de pornografia (porn):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`sexy`	Conteúdo sensual
`porn`	Conteúdo pornográfico

Detecção de terrorismo e conteúdo politicamente sensível (terrorism):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`bloody`	Conteúdo sangrento
`explosion`	Efeitos de fumaça e luz
`outfit`	Vestimenta especial
`logo`	Logotipo especial
`weapon`	Arma
`politics`	Politicamente sensível
`violence`	Luta
`crowd`	Multidão
`parade`	Protesto
`carcrash`	Acidente de carro
`flag`	Bandeira
`location`	Ponto de referência
`drug`	Relacionado a drogas
`gamble`	Jogo de azar
`others`	Outros

Detecção de violação de anúncio (ad):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`ad`	Outro anúncio
`politics`	Texto com conteúdo politicamente sensível
`porn`	Texto com conteúdo pornográfico
`abuse`	Texto com conteúdo abusivo
`terrorism`	Texto com conteúdo terrorista
`contraband`	Texto com conteúdo proibido
`spam`	Texto com spam
`npx`	Anúncio de spam
`qrcode`	QR code
`programCode`	Código de mini programa

Detecção de QR code (qrcode):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`qrcode`	QR code
`programCode`	Código de mini programa

Detecção de cena indesejável (live):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`meaningless`	Sem conteúdo (tela preta, tela branca, etc.)
`PIP`	Picture-in-Picture (PiP)
`smoking`	Fumando
`drivelive`	Transmissão ao vivo dentro do carro
`drug`	Relacionado a drogas
`gamble`	Jogo de azar

Detecção de logotipo (logo):

Rótulo	Descrição
`normal`	Nenhuma violação detectada
`TV`	Logotipo controlado (logotipo de emissora de TV)
`Trademark`	Marca registrada

frame

Parâmetro	Tipo	Exemplo	Descrição
`rate`	Float	`89.85`	A pontuação de confiança, de `0` a `100`. Não utilize este valor na lógica de negócios.
`url`	String	`http://www.example.com/image-0.jpg`	A URL temporária do quadro. Válida por 5 minutos.

programCodeData

Parâmetro	Tipo	Exemplo	Descrição
`x`	Float	`11.0`	A coordenada x do canto superior esquerdo da região do código de mini programa. A origem é o canto superior esquerdo da imagem. Unidade: pixel.
`y`	Float	`0.0`	A coordenada y do canto superior esquerdo da região do código de mini programa. A origem é o canto superior esquerdo da imagem. Unidade: pixel.
`w`	Float	`402.0`	A largura da região do código de mini programa. Unidade: pixel.
`h`	Float	`413.0`	A altura da região do código de mini programa. Unidade: pixel.

logoData

Parâmetro	Tipo	Exemplo	Descrição
`type`	String	`TV`	O tipo de logotipo. `TV` indica um logotipo de emissora de TV.
`name`	String	`Example TV`	O nome do logotipo detectado.
`x`	Float	`140`	A coordenada x do canto superior esquerdo da região do logotipo. Unidade: pixel.
`y`	Float	`68`	A coordenada y do canto superior esquerdo da região do logotipo. Unidade: pixel.
`w`	Float	`106`	A largura da região do logotipo. Unidade: pixel.
`h`	Float	`106`	A altura da região do logotipo. Unidade: pixel.

sfaceData

Parâmetro	Tipo	Exemplo	Descrição
`x`	Float	`49`	A coordenada x do canto superior esquerdo da região do rosto. Unidade: pixel.
`y`	Float	`39`	A coordenada y do canto superior esquerdo da região do rosto. Unidade: pixel.
`w`	Float	`97`	A largura da região do rosto. Unidade: pixel.
`h`	Float	`131`	A altura da região do rosto. Unidade: pixel.
`faces`	JSONArray	—	Os rostos detectados. Cada elemento contém: `name` (String, nome da pessoa correspondente), `rate` (Float, pontuação de confiança de 0–100), `id` (String, ID do rosto).

hitLibInfo

Parâmetro	Tipo	Exemplo	Descrição
`context`	String	`Haokan Video`	O texto correspondente da biblioteca personalizada.
`libCode`	String	`123456`	O código da biblioteca personalizada que contém o texto correspondente.
`libName`	String	`My text library`	O nome da biblioteca personalizada que contém o texto correspondente.

hintWordsInfo

Parâmetro	Tipo	Exemplo	Descrição
`context`	String	`Good video`	A palavra-chave de risco correspondente na imagem.

qrcodeLocation

Parâmetro	Tipo	Exemplo	Descrição
`x`	Float	`11.0`	A coordenada x do canto superior esquerdo da região do QR code. Unidade: pixel.
`y`	Float	`0.0`	A coordenada y do canto superior esquerdo da região do QR code. Unidade: pixel.
`w`	Float	`402.0`	A largura da região do QR code. Unidade: pixel.
`h`	Float	`413.0`	A altura da região do QR code. Unidade: pixel.
`qrcode`	String	`http://www.example.com/0.ZZOliO`	A URL ou conteúdo codificado no QR code detectado.

Exemplo

Solicitação:

http(s)://[Endpoint]/green/image/results
&<Common request parameters>

["fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]

Resposta:

{
    "msg": "OK",
    "code": 200,
    "requestId": "69B41AE8-1234-1234-1234-12D395695D2D",
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
            "extras": {},
            "results": [
                {
                    "scene": "porn",
                    "label": "sexy",
                    "suggestion": "block",
                    "rate": 99.63
                },
                {
                    "scene": "terrorism",
                    "label": "politics",
                    "suggestion": "block",
                    "rate": 91.54,
                    "sfaceData": [
                        {
                            "x": 49,
                            "y": 39,
                            "w": 97,
                            "h": 131,
                            "faces": [
                                {
                                    "id": "AliFace_0001234",
                                    "name": "Hit name",
                                    "rate": 91.54
                                }
                            ]
                        }
                    ]
                },
                {
                    "scene": "ad",
                    "label": "ad",
                    "suggestion": "block",
                    "rate": 99.91,
                    "extras": {
                        "qrcodes": "http://www.aliyundoc.com/0.ZZOliO",
                        "npx": "72.01",
                        "hitCustomLibCode": "8012345000",
                        "hitCustomLibName": "Name of the custom image library",
                        "hitLibInfo": [
                            {
                                "context": "Hit text",
                                "libCode": "123456",
                                "libName": "Name of the custom text library"
                            }
                        ]
                    },
                    "programCodeData": [
                        {
                            "x": 11.0,
                            "y": 0.0,
                            "w": 402.0,
                            "h": 413.0
                        }
                    ],
                    "frames": [
                        {
                            "rate": 89.85,
                            "url": "http://www.aliyundoc.com/xxx-0.jpg"
                        },
                        {
                            "rate": 68.06,
                            "url": "http://www.aliyundoc.com/xxx-1.jpg"
                        }
                    ]
                },
                {
                    "scene": "live",
                    "label": "drug",
                    "suggestion": "block",
                    "rate": 99.91
                },
                {
                    "scene": "qrcode",
                    "label": "qrcode",
                    "suggestion": "review",
                    "rate": 99.91,
                    "qrcodeData": [
                        "http://www.aliyundoc.com/01ZZOliO"
                    ]
                },
                {
                    "scene": "logo",
                    "label": "TV",
                    "suggestion": "block",
                    "rate": 99.9,
                    "logoData": [
                        {
                            "name": "xxx TV",
                            "type": "TV",
                            "x": 140,
                            "y": 68,
                            "w": 106,
                            "h": 106
                        }
                    ]
                }
            ]
        }
    ]
}