# AI API v3

### Visão geral

* Padrão OpenAPI 3.0.3.
* Foco em agentes (texto e multimodal), LLM, TTS/STT, pipelines de áudio, insights e jornada do cliente.
* Todas as chamadas são multi-tenant. Tenha `tenant` no caminho da URL.
* Formatos aceitos: `application/json` e `multipart/form-data` (para upload de áudio, PDF, imagem e arquivos multimídia).

### Base URL

* Produção: `https://app.genier.ai/{tenant}/api/v3/`
* Host configurável via variável de caminho `{host}` quando aplicável.

### Autenticação

* Header: `Authorization: <API_KEY>`.
* Sem prefixo Bearer. A chave é enviada direta no valor do header.
* Requisições sem header válido retornam `401` com corpo `{"message": "Auth Error"}`.

#### Como obter a API Key

1. Acesse o painel da sua conta na **Fortics AI**.
2. Navegue até o menu **Configurações > API**.
3. Clique em **Nova Chave de API**.
4. Copie a chave gerada e armazene-a em local seguro.

> ⚠️ **Importante:**
>
> * Não compartilhe sua chave publicamente.
> * Em caso de exposição, revogue imediatamente e gere uma nova.

### Principais recursos

* Agentes: execução texto (`/agent/{agent_id}`), Multimodal (`/agent_mm/{agent_id}`, listagem (`/agent_list`), voz do agente (`/agent_voice`).
* Processamento: Geração (`/generate`, `/generate_mem`, `/search`).
* Voz: TTS (`/tts`), STT (`/stt_transcribe`), pipelines de áudio (`/voiceverse`, `/voiceverse_list`, `/voiceverse_content/{pipeline_id}`).
* OCR: extração de texto (`/ocr`).
* Insights: templates (`/insights_chat`), enfileirar workflow (`/insights_chat` POST), buscar template (`/insights_chat/{insight_id}`), insights imediatos legados (`/chat_insights`), relatórios (`/reports/insights`).
* Jornada e resumos: jornada do cliente (`/customer_journey`), curadoria (`/go_curator`).

### Exemplos rápidos

#### Executar agente de texto

```bash
curl -X POST \
  "https://app.genier.ai/my-tenant/api/v3/agent/agent_1234abcd" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_KEY>" \
  -d '{
    "query": "Como funciona o produto?",
    "history": [{"input": "Oi", "output": "Olá, posso ajudar."}],
    "tts": false
  }'
```

#### STT (multipart)

```bash
curl -X POST \
  "https://app.genier.ai/my-tenant/api/v3/stt_transcribe" \
  -H "Authorization: <API_KEY>" \
  -F "file=@audio.wav" \
  -F "data={\"lang\":\"pt-BR\"}"
```

#### Workflow de insights de chat (enqueue)

```bash
curl -X POST \
  "https://app.genier.ai/my-tenant/api/v3/insights_chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_KEY>" \
  -d '{
    "id": "session-123",
    "insight_chat_id": "4f8ba8d7-090e-4a29-9e63-1f2d2f9e0c7a",
    "url": "https://webhook.seusistema.com/retorno-insights",
    "data": {"conversation": [{"from": "cliente", "text": "Olá"}]}
  }'
```

### Códigos de resposta comuns

* `200`: Operação concluída; retorna dados do recurso ou resultado do processamento.
* `202`: Requisição enfileirada para processamento assíncrono (ex.: insights\_chat POST).
* `400`: Validação falhou; campos obrigatórios ausentes ou payload inválido.
* `401`: Autenticação inválida ou ausente.
* `403`: Conteúdo ou operação não permitida pelo modo configurado.
* `404`: Recurso, configuração ou template não encontrado.
* `413`: Tamanho de arquivo excede o limite.
* `415`: Tipo de mídia não suportado.
* `500`: Erro interno ao processar a requisição.

### Boas práticas

* Sempre inclua `tenant` na URL.
* Para uploads, respeite limites de tamanho e tipos aceitos indicados na spec.
* Guarde `workflow_id` retornado em operações assíncronas para consultar status ou cancelar.
* Para multimodal, serialize `history` corretamente em JSON (ou string JSON em multipart).


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fortics.com.br/ai-api-reference/ai-api-v3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.