> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/geral/conceitos-chave-do-oz-liveness-e-biometry/oz-api-key-concepts.md).

# Conceitos-chave do Oz API

A Oz API é uma API REST abrangente que habilita biometria facial, permitindo tanto correspondência facial quanto verificações de Liveness. Este texto fornece uma visão geral dos conceitos essenciais que devem ser mantidos em mente ao usar a Oz API.

### Autenticação, funções e gerenciamento de acesso

Para garantir a segurança, toda chamada à Oz API requer um token de acesso em seus cabeçalhos HTTP. Para obter esse token, execute o `POST /api/authorize/auth` método com login e senha fornecidos por nós. Passe esse token no `X-Forensic-Access-Token` cabeçalho nas chamadas subsequentes à Oz API.

[Este artigo](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/use-cases/authentication.md) fornece detalhes abrangentes sobre o processo de autenticação. Consulte-o para mais informações.

Além disso, a Oz API oferece funções de usuário distintas, variando de `CLIENT`, que pode executar verificações e acessar relatórios, mas não possui direitos administrativos, por exemplo, excluir pastas, até `ADMIN`, que desfruta de acesso quase irrestrito a todos os objetos do sistema. Para mais informações, consulte [este guia](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/user-roles.md).

### Persistência

A unidade de trabalho na Oz API é uma **folder**: você pode carregar mídias inter-relacionadas para uma pasta, executar análises sobre elas e verificar o resultado agregado. Uma pasta pode conter um número ilimitado de mídias, e cada mídia pode ser alvo de várias análises. Além disso, análises podem ser executadas em um conjunto de mídias.

<figure><img src="https://2275968150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5g6dgsxRbyrCvB0uAf8f%2Fuploads%2FJxx0asFR031C1M1KYPuo%2Fer%20api%20basics%20New.drawio%20(1).png?alt=media&amp;token=51156a9a-3ca2-447c-a901-8fbee730f6b0" alt=""><figcaption></figcaption></figure>

### &#x20;Tipos de mídia e tags

A Oz API trabalha com fotos e vídeos. Um vídeo pode ser tanto um contêiner de vídeo regular, por exemplo, MP4 ou MOV, quanto um arquivo ZIP com uma sequência de imagens. A Oz API usa o tipo MIME do arquivo para definir se a mídia é uma imagem, um vídeo ou um conjunto de capturas.

Também é importante determinar a semântica de um conteúdo, por exemplo, se uma imagem é a foto de um documento ou uma selfie de uma pessoa. Isso é alcançado por meio do uso de tags. A seleção de tags influencia se tipos específicos de análises reconhecerão ou ignorarão arquivos de mídia específicos. As tags mais importantes são:

* `photo_id_front` – para o lado frontal de um documento de identidade com foto
* `photo_selfie` – para uma foto de referência que não seja de documento
* `video_selfie_blank` – para um vídeo de Liveness gravado fora do Oz Liveness SDK
* se um arquivo de mídia for capturado usando o Oz Liveness SDK, as tags são atribuídas automaticamente.

A lista completa das tags de mídia da Oz com suas explicações e exemplos pode ser encontrada [aqui](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/media-tags.md).

### Análises assíncronas

Como a análise de vídeo pode levar alguns segundos, as análises são executadas de forma assíncrona. Isso implica que você inicia uma análise (`/api/folders/{{folder_id}}/analyses/`) e então monitora os resultados por polling até que o processamento seja concluído (`/api/analyses/{{analysis_id}}` para uma única análise ou `/api/folders/{{folder_id}}/analyses/` para todas as análises da pasta). Como alternativa, há uma opção de webhook disponível. Para ver um exemplo de como usar as opções de polling e webhook, consulte [este guia](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/basic-scenarios/liveness.md#processing-steps).

Estes foram os conceitos-chave da Oz API. Para obter uma compreensão mais profunda de suas capacidades, consulte a [seção da Oz API](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api.md) do nosso guia do desenvolvedor.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/geral/conceitos-chave-do-oz-liveness-e-biometry/oz-api-key-concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
