Criar asset
Registra um asset a partir de uma URL com validação opcional e metadados
Use POST {{BASE_URL}}/assets/create, onde {{BASE_URL}} é o valor de ASSETS_HANDLER_URL (normalmente termina em /api, por exemplo http://localhost:8000/api).
O código do assets-handler não aplica middleware de API Key nas rotas /api/assets; proteção costuma ser rede interna ou gateway. Para chamadas via backend-service, existe o proxy POST https://api.tolky.to/api/assets/create (exige hostId no body e encaminha para o handler).
Endpoint
POST {{BASE_URL}}/assets/create
Parâmetros
URL da mídia a registrar (obrigatória para o fluxo principal).
ID do usuário proprietário.
ID do host associado.
ID do avatar associado.
ID da conversa, quando aplicável.
Categoria do asset; o serviço também deriva tipo a partir do MIME quando possível.
MIME explícito; se omitido, pode ser inferido via health check ou detecção.
Se true, executa health check da URL antes de criar; falha se o link não estiver acessível.
Se true, se já existir asset para a URL sanitizada, retorna o existente em vez de criar outro.
Se true, tenta criar URL encurtada (Kutt) após a inserção.
Se true, dispara fluxo de descrição de mídia conforme implementação do serviço (pode usar fila).
Nome lógico do bucket usado em integrações de armazenamento.
Campos extras permitidos na tabela assets (filtrados pelo backend contra o schema).
Instruções opcionais para o fluxo de descrição de mídia.
Modo de fila RabbitMQ quando aplicável (ex.: enfileirar criação).
Nome da fila quando queueMode enfileira mensagens.
ID de controle de requisição para rastreio.
Exemplo
curl -X POST "{{BASE_URL}}/assets/create" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/documents/contract.pdf",
"hostId": "660e8400-e29b-41d4-a716-446655440001",
"type": "document",
"needCheckUrl": false,
"needCheckExisting": true,
"needCreateShortUrl": true,
"needMediaDescription": false
}'
Resposta
Corpo típico em sucesso (asset novo):
{
"created": true,
"alreadyExists": false,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"file_url": "https://example.com/documents/contract.pdf",
"bucket_url": null,
"short_url": null,
"host_id": "660e8400-e29b-41d4-a716-446655440001",
"mime_type": "application/pdf",
"type": "document",
"deleted": false
}
}
Com needCheckUrl: true, pode vir um objeto healthCheck no mesmo nível com url, ok, status, mimeType, type.
Se o header Host da requisição estiver presente, o handler acrescenta data.download_url como https://<host>/api/assets/download/<id> (útil quando o cliente chama o serviço pelo nome público do cluster ou domínio).
Campos da resposta
Indica se um novo registro foi criado.
Indica se a URL já existia e o registro foi reutilizado.
Linha do asset em public.assets (inclui file_url, bucket_url, short_url, ids, mime_type, type, etc.).
Presente quando needCheckUrl foi usado; ecoa resultado do verificador de link.
Proxy no backend-service
POST /api/assets/create (base https://api.tolky.to) valida url e hostId, monta o payload com needCreateShortUrl, needCheckUrl, needCheckExisting e chama ${ASSETS_HANDLER_URL}/assets/create. A resposta é encapsulada pelo framework de API (Response.success) e pode incluir downloadUrl derivado.
Erros
| Código | Descrição |
|---|---|
400 | Validação (URL ausente, sanitização inválida, URL inacessível com needCheckUrl) |
500 | Falha interna ou erro não tratado |
O handler costuma retornar JSON com error: { message, code, location, status } — ver Erros.
Endpoint relacionado
POST {{BASE_URL}}/assets/create-conversational aceita urls, url ou currentMessage para extrair várias URLs e criar em lote (ver código em assets-handler).