Referência da API

v4 · Integração de terceiros

— Auth —

— Tarefas —

— Envios —

— Pastas —

— Usuário —

— Notificações —

— Checkout —

Documentação da API

API REST para transcrição de áudio e vídeo. Clientes pagos autenticam integrações de terceiros com uma chave de API criada nas configurações da conta.

URL base

https://scribe.uustudio.cc

Autenticação

Integrações de terceiros devem enviar uma chave de API de uma conta paga no cabeçalho Authorization.

Cabeçalho Authorization

Authorization: Bearer {token}

Crie e revogue chaves na página de Chaves de API das configurações. Os endpoints de autenticação do app são reservados aos clientes oficiais.

Respostas de erro

Todos os erros retornam um corpo JSON com um campo message .

Erro padrão

{
    "message": "Description of the error"
}

Erro de validação (422)

{
    "message": "The name field is required.",
    "errors": {
        "name": ["The name field is required."]
    }
}

Status	Descrição
401	Não autenticado (token ausente ou inválido)
403	Proibido ou limite do plano excedido
404	Recurso não encontrado
422	Falha na validação
429	Taxa limitada ou muitas tarefas simultâneas
500	Erro interno do servidor

Limites de taxa

Endpoints de API autenticados são limitados a 10 solicitações por minuto por token.

Limites de uso

Disponibilidade da API

A API REST de terceiros não está disponível no plano Gratuito. Assine Pro ou Max, ou compre um pacote pré-pago, para criar e usar chaves de API.

Tamanho máximo de arquivo: 2 GB
Tarefas simultâneas: Máx 3
Máximo de tentativas por tarefa: 3

Comparação de planos pagos

Recurso	Pay as you go	Pro	Max
Envios diários	Ilimitado	Ilimitado	Ilimitado
Formatos de exportação	Todos	Todos	Todos
Prioridade de tarefas	Média	Média	Alta

Fluxos de trabalho

Enviar arquivo de áudio/vídeo

POST /api/uploads/sign → Obter upload_id e informações da parte
PUT {presigned_url} → Enviar cada parte para o armazenamento
POST /api/uploads/complete → Finalizar envio, criar tarefa automaticamente
GET /api/tasks/{id} → Consultar status (pending -> scribing -> finished)
GET /api/tasks/{id}/download/srt → Exportar (opcional)

Criar tarefa manualmente

POST /api/tasks → Criar com disk, path, name
GET /api/tasks/{id} → Consultar status
GET /api/tasks/{id} → Obter segments, summary, mindmap

Auth

POST /api/login

Autentique-se com e-mail e senha. Retorna um token Sanctum.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
email	string	Yes	E-mail do usuário (máx 255)
password	string	Yes	Senha do usuário

Resposta 200

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

Limitado a 5 tentativas por minuto por e-mail.

POST /api/register

Crie uma conta nova. Retorna um token Sanctum.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Yes	Nome de exibição (máx 255)
email	string	Yes	E-mail único (máx 255)
password	string	Yes	Deve ser confirmado
password_confirmation	string	Yes	Confirmação de senha

Resposta 201

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

POST /api/auth/social-login

Autentique-se via Google OAuth. Cria uma conta se não existir.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
provider	string	Yes	`google` provedores suportados
code	string	Yes	Código de autorização OAuth

Resposta 200

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

POST /api/logout

Revoga o token de acesso atual.

Resposta 204

Não retorna corpo.

Tarefas

POST /api/tasks

Cria uma tarefa de transcrição. Máx 3 tarefas simultâneas por usuário.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
disk	string	Yes	`r2` / `remote` / `youtube` Identificador da fonte de armazenamento
name	string	Yes	Nome da tarefa (máx 255)
path	string	Yes	Caminho do arquivo ou URL de origem
file	string	No	Nome de arquivo original (máx 255)
size	integer	No	Tamanho do arquivo em bytes
duration	integer	No	Duração em segundos
cost	integer	No	Custo em segundos
segments	array	No	Segmentos de transcrição
speaker_diarization	boolean	Não	app.tasks.speaker_diarization_api_description

Resposta 201

{
    "id": 1,
    "name": "Meeting Recording",
    "status": "pending",
    "speaker_diarization": true,
    "created_at": "2026-03-02T10:30:00+08:00"
}

Erros

Status	Descrição
403	Usuários gratuitos não podem enviar links do YouTube pela API.
429	Máximo de 3 tarefas simultâneas atingido

GET /api/tasks/{id}

Obtém detalhes completos da tarefa, incluindo resultados de transcrição.

Resposta

{
    "id": 1,
    "name": "Meeting Recording",
    "file": "meeting.mp3",
    "path": "2026-03-02/01HQX...mp3",
    "disk": "r2",
    "size": 50545869,
    "duration": 1965,
    "cost": 33,
    "status": "finished",
    "attempts": 1,
    "quality": 3,
    "created_at": "2026-03-02T10:30:00+08:00",
    "updated_at": "2026-03-02T10:45:00+08:00",
    "summary": "The meeting discussed three topics...",
    "mindmap": "# Topic\n## Sub-topic 1",
    "folder": "Work",
    "tags": ["Work"],
    "url": "https://youtube.com/watch?v=...",
    "segments": [
        {
            "id": 1,
            "start": 0,
            "end": 5000,
            "speaker": "Speaker 1",
            "tokens": ["Okay", "so let's", "begin"],
            "text": "Okay, so let's begin..."
        }
    ],
    "export": {
        "allowed_formats": ["txt", "srt", "vtt", "csv", "pdf", "docx"],
        "heavy_formats": ["pdf", "docx"],
        "version": "20260302104500"
    }
}

Campos de resposta

Campo	Tipo	Descrição
disk	string\|null	Disco de armazenamento: r2 / remote / youtube
size	int\|null	Tamanho do arquivo em bytes
cost	int\|null	Custo em segundos
attempts	int	Contagem de tentativas
quality	int\|null	Pontuação de qualidade (0-5)
summary	string\|null	Resumo gerado por IA
mindmap	string\|null	Mapa mental gerado por IA
folder	string\|null	Nome da primeira tag (pasta)
tags	array	Todos os nomes de tags
url	string\|null	URL de origem (para tarefas YouTube)
segments	array\|null	Segmentos de transcrição
segments[].start	int	Tempo de início (ms)
segments[].end	int	Tempo de fim (ms)
segments[].text	string	Texto do segmento
segments[].speaker	string\|null	Identificador do interlocutor
segments[].tokens	array\|null	Array de tokens de palavras
export	object	Metadados de exportação (allowed_formats, heavy_formats, version)

GET /api/tasks

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
status	string	all	Filtrar por status
search	string	—	Pesquisar por nome
folder	string	—	Filtrar por pasta (ou `Uncategorized`)
page	int	1	Número da página
per_page	int	25	Itens por página (máx 100)

Resposta

{
    "data": [
        {
            "id": 1,
            "name": "Meeting Recording",
            "file": "meeting.mp3",
            "disk": "r2",
            "size": 50545869,
            "duration": 1965,
            "cost": 33,
            "status": "finished",
            "attempts": 1,
            "quality": 3,
            "folder": "Work",
            "created_at": "2026-03-02T10:30:00+08:00"
        }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
}

PATCH /api/tasks/{id}/retry

Tentar novamente uma tarefa com falha. Define o status para pending (R2) ou waiting (remote/YouTube). Máx 3 tentativas.

Resposta 200

{
    "id": 1,
    "status": "pending",
    "attempts": 2
}

GET /api/tasks/{id}/download/{format}

Exportar transcrição. Formatos leves retornam o arquivo diretamente. Formatos pesados (pdf/docx) podem retornar 202 durante o processamento.

Parâmetros de caminho

Parâmetro	Descrição
format	`txt` / `srt` / `vtt` / `csv` / `pdf` / `docx`

Respostas

200 - Arquivo pronto (formatos leves)

Retorna um arquivo binário.

200 - Arquivo pronto (formatos pesados, requisição JSON)

{
    "status": "ready",
    "url": "https://scribe.uustudio.cc/api/tasks/1/download/pdf"
}

202 - Processando formato pesado

{
    "status": "processing",
    "message": "Your export is being generated. Please try again shortly."
}

GET /api/tasks/{id}/audio

Transmitir o arquivo de áudio ou vídeo original diretamente do armazenamento (apenas R2).

Resposta

200 - Fluxo binário do arquivo de áudio ou vídeo. Retorna 404 se o arquivo estiver ausente ou não estiver no disco R2.

GET /api/tasks/{id}/refresh-summary

Atualizar e retornar o resumo e mapa mental mais recentes gerados por IA.

Resposta

{
    "summary": "The meeting discussed three topics...",
    "mindmap": "# Topic\n## Sub-topic 1"
}

PATCH /api/tasks/{id}

Atualizar campos da tarefa. Todos os campos são opcionais.

Corpo da requisição

Campo	Tipo	Descrição
name	string	Novo nome (máx 255)
folder	string\|null	Nome da pasta (null remove a tarefa de uma pasta)
duration	integer	Duração em segundos
cost	integer	Custo em segundos
segments	array	Array completo de segmentos para substituir
text	string	Texto completo da transcrição
quality	integer	Pontuação de qualidade (0-5)
index	integer	Índice de ordenação da tarefa

Resposta 200

Retorna o objeto de tarefa completo (igual a Detalhe da tarefa).

DELETE /api/tasks/{id}

Response 200

{
    "message": "Task deleted successfully"
}

DELETE /api/tasks/bulk

Excluir múltiplas tarefas de uma vez. Apenas tarefas do usuário autenticado serão excluídas. IDs que não pertencem ao usuário são ignorados.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
ids	array	Yes	Array de IDs de tarefas a excluir (mín 1)

Resposta 200

{
    "message": "2 task(s) deleted successfully",
    "deleted_count": 2
}

PATCH /api/tasks/bulk/move

Mover múltiplas tarefas para uma pasta de uma vez. Apenas tarefas do usuário autenticado serão movidas.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
ids	array	Yes	Array de IDs de tarefas a mover (mín 1)
folder	string	Yes	Nome da pasta de destino (máx 255)

Resposta 200

{
    "message": "2 task(s) moved to Work",
    "moved_count": 2
}

Envios

Envio multipart

POST /api/uploads/sign

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
file	string	Yes	Nome do arquivo (deve usar um formato suportado)
content_type	string	Yes	Tipo MIME (deve corresponder à extensão do arquivo)
size	integer	Yes	Tamanho do arquivo em bytes (máx 2.147.483.648 / 2 GB)
duration	integer	No	Duração do áudio em segundos

Resposta

{
    "path": "2026-03-02/01HQX...mp3",
    "upload_id": "abc123",
    "part_size": 5242880,
    "part_count": 10,
    "expires_at": "2026-03-02T10:40:00+08:00"
}

POST /api/uploads/sign-part

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
path	string	Yes	Caminho de envio (máx 2048)
upload_id	string	Yes	ID do envio (máx 2048)
part_number	integer	Yes	Número da parte (1-10000)

Resposta

{
    "url": "https://storage.example.com/...?X-Amz-...",
    "headers": {
        "Content-Type": "audio/mpeg"
    }
}

Use PUT com a URL e cabeçalhos retornados para enviar a parte.

POST /api/uploads/complete

Completar um envio multipart. Isso cria automaticamente uma tarefa e retorna 403 quando a API não está disponível ou um limite do plano é excedido.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
path	string	Yes	Caminho de envio (máx 2048)
upload_id	string	Yes	ID do envio (máx 2048)
original_name	string	Yes	Nome de arquivo original (deve usar um formato suportado)
content_type	string	Yes	Tipo MIME (deve corresponder à extensão do arquivo)
size	integer	Yes	Tamanho do arquivo em bytes (máx 2 GB)
name	string	No	Nome da tarefa (padrão para o nome do arquivo sem extensão)
duration	integer	No	Duração em segundos (mín 1)
speaker_diarization	boolean	Não	app.tasks.speaker_diarization_api_description

Resposta 201

{
    "message": "File uploaded to the upload server successfully.",
    "task": {
        "id": 1,
        "name": "meeting",
        "path": "2026-03-02/01HQX...mp3",
        "size": 50545869,
        "status": "pending",
        "speaker_diarization": true
    }
}

POST /api/uploads/abort

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
path	string	Yes	Caminho de envio (máx 2048)
upload_id	string	Yes	ID do envio (máx 2048)

Resposta

{
    "message": "Multipart upload cancelled successfully."
}

Pastas

Baseado em tags

GET /api/folders

Liste todas as pastas com contagens de tarefas.

Resposta

{
    "folders": [
        {"id": 1, "name": "Work", "count": 5},
        {"id": 2, "name": "Personal", "count": 3}
    ],
    "uncategorized_count": 2,
    "total_count": 10
}

POST /api/folders

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Yes	Nome da pasta (máx 14 caracteres / 7 caracteres chineses, único por usuário)

Resposta 201

{
    "id": 1,
    "name": "Work"
}

PATCH /api/folders/{name}

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Yes	Novo nome da pasta (mesmas restrições que criar)

Resposta 200

{
    "id": 1,
    "name": "New Name"
}

DELETE /api/folders/{name}

Response 200

{
    "message": "Folder deleted successfully"
}

Usuário

GET /api/user

Resposta

{
    "id": 1,
    "name": "Zhang San",
    "email": "[email protected]",
    "avatar": "https://...",
    "balance": {
        "used_seconds": 9000,
        "remaining_seconds": 36000,
        "allowance_remaining_seconds": 30000,
        "top_up_remaining_seconds": 6000,
        "total_seconds": 45000,
        "usage_percent": 20
    },
    "subscription": {
        "plan": "year",
        "plan_key": "max_yearly",
        "tier": "max",
        "billing_interval": "yearly",
        "active": true,
        "access_tier": "max"
    },
    "queue": {
        "pending_count": 1,
        "running_count": 1,
        "failed_count": 0
    }
}

Campos de saldo

Campo	Tipo	Descrição
used_seconds	int	Segundos usados desde a última concessão mensal
remaining_seconds	int	Segundos restantes
total_seconds	int	Total de segundos
usage_percent	int	Porcentagem de uso (0-100)

PUT /api/user

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	No	Nome de exibição (máx 255)
email	string	Não	Novo e-mail (deve ser único)
avatar	file	No	Arquivo de imagem (máx 5 MB)

Resposta 200

{
    "id": 1,
    "name": "New Name",
    "email": "[email protected]",
    "avatar": "https://..."
}

Notificações

GET /api/notifications

Obter as 10 notificações mais recentes.

Resposta

[
    {
        "id": "abc123",
        "title": "Task Completed",
        "message": "Meeting Recording has been transcribed.",
        "read_at": null,
        "created_at": "2026-03-02T10:45:00+08:00"
    }
]

POST /api/notifications/mark-all-as-read

Marcar todas as notificações não lidas como lidas.

Response 200

{
    "success": true
}

Checkout

GET /api/checkout/{plan}

Obter uma URL de checkout da Paddle para um plano de assinatura.

Parâmetros de caminho

Parâmetro	Descrição
plan	`test` / `month` / `year`

Resposta

Retorna um objeto de opções de checkout da Paddle. Retorna 404 para um plano inválido.

GET /api/health

Endpoint público de verificação de integridade. Não requer autenticação.

Resposta 200

{
    "status": "ok"
}

Ler Termos · Ler Política de Privacidade · Voltar para casa