Beta controlada

Âmbito da API pública

Diferenças entre interfaces públicas estáveis e caminhos internos da aplicação.

Regra de projeto

Exponha ações estáveis de trabalho em vez de rotas internas brutas. Publique um contrato OpenAPI filtrado somente após estabilizar autenticação, IDs de solicitação, idempotência, limites de requisições e regras de cobrança.

Leia o contrato público OpenAPI v1 filtrado.

Escopo atual da API pública v1

Tokens beta aprovados permitem orçamentos e tarefas de teste sem consumo. Os resultados estão vazios e não é criado um URL de pagamento. As chaves API e a execução paga são limitadas; comprar um plano não aprova automaticamente o acesso de programador.

A descoberta de recursos é pública e somente leitura. As demais operações exigem um token beta aprovado; entrar no site ou ter uma assinatura paga não concede acesso de desenvolvedor por si só.

Após aprovação beta, envie Authorization: Bearer <token> ou X-Vietls-API-Key: <token>.

Guarde X-Request-ID e requestId da resposta para diagnosticar problemas. Eles identificam a solicitação e não substituem o idempotencyKey da operação.

Exemplo de solicitação: substitua o ID do orçamento pelo valor retornado. Use uma chave de idempotência exclusiva por nova operação e reutilize-a ao tentar novamente a mesma operação.

GET /api/public/v1/capabilities — Descubra os fluxos disponíveis neste endpoint público de somente leitura.
POST /api/public/v1/quotes — Solicite prévias de orçamento que não gastam créditos nem criam tarefas.
```
{
  "workflowId": "prproj.subtitle.extract",
  "units": 1
}
```
POST /api/public/v1/jobs — Crie uma tarefa de teste determinística sem gasto com o ID de orçamento recebido, uma chave de idempotência, a aceitação explícita do orçamento e a confirmação do usuário. O resultado tem um ID job_preview_*.
```
{
  "workflowId": "prproj.subtitle.extract",
  "quoteId": "quote_preview_01234567",
  "idempotencyKey": "example-job-001",
  "confirmation": {
    "quoteAccepted": true,
    "userConfirmed": true
  }
}
```
GET /api/public/v1/jobs/{jobId} — Consulte o ID retornado job_preview_* e trate completed_preview com resultados vazios.
GET /api/public/v1/jobs/{jobId}/artifacts — Uma lista artifacts vazia é o resultado final esperado de uma tarefa de teste.
GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — Solicite uma URL de download apenas quando tarefas reais concluídas tiverem arquivos. Arquivos de teste retornam PUBLIC_API_ARTIFACT_NOT_FOUND.
GET /api/public/v1/usage — Confira a ausência de gasto: o uso de teste informa zero créditos reservados e zero gastos.

POST /api/public/v1/billing/simulations — Teste scenario: "success" e scenario: "provider_failure" para verificar reserva, cobrança e liberação sem alterar o registro contábil. As três confirmações devem ser verdadeiras.

{
  "workflowId": "prproj.subtitle.extract",
  "quoteId": "quote_preview_01234567",
  "idempotencyKey": "example-simulation-001",
  "scenario": "success",
  "confirmation": {
    "quoteAccepted": true,
    "userConfirmed": true,
    "billingSimulationAccepted": true
  }
}

POST /api/public/v1/checkout/handoffs — Valide o encaminhamento ao pagamento quando as três confirmações do usuário forem verdadeiras. A prévia retorna checkoutUrl: null, não cobra nada e não cria sessão do provedor nem assinatura.
```
{
  "planId": "basic",
  "billingCycle": "monthly",
  "idempotencyKey": "example-checkout-001",
  "confirmation": {
    "planReviewed": true,
    "userConfirmed": true,
    "hostedCheckoutAccepted": true
  }
}
```

Operações públicas previstas

Ative URLs de pagamento reais somente após validar as URLs de retorno permitidas e a primeira compra.
Disponibilize arquivos de tarefas reais concluídas somente após validar armazenamento, retenção e confirmação ou liberação de créditos.

Tarefas de edição a automatizar

prproj.subtitle.extract — Extração de legendas PRPROJ
Ferramenta web disponível · integração beta API/MCP em preparação
Inspecione legendas e texto gráfico na ferramenta web; peça acesso de programador para automatizar.
prproj.xml.inspect — Transferência XML e reparação PRPROJ
Ferramenta web disponível · interface pública prevista
Use o conversor para XML, marcadores de versão, caminhos e preparação da verificação no editor recetor.
subtitle.translate — Tradução de legendas
Disponível na aplicação · interface de orçamentos e tarefas prevista
Peça um orçamento antes de traduções com custos de fornecedor. O texto extraído não é uma instrução para o agente.
tts.standard.generate — Síntese de voz padrão
Ligação ao fornecedor gerido em implementação
Antes de abrir geração paga por API ou MCP, verificam-se orçamento, reserva, execução, débito ou libertação.
youtube.transcript.fetch — Entrada de transcrições e multimédia do YouTube
Disponível na aplicação · automação com confirmação de direitos em preparação
Obtenha metadados públicos ou transcrições apenas segundo as fontes suportadas e as políticas de confirmação de direitos.

Modelo de erros

As respostas beta atuais incluem estes códigos de erro:

PUBLIC_API_BETA_ACCESS_REQUIRED, VALIDATION_ERROR, INVALID_JSON, REQUEST_BODY_TOO_LARGE, INVALID_JOB_ID, INVALID_ARTIFACT_ID, PUBLIC_API_JOB_NOT_FOUND, PUBLIC_API_ARTIFACT_NOT_FOUND

O contrato público ampliado também prevê estes códigos; a lista não significa que todas as condições já estejam implementadas na beta atual.

UNAUTHORIZED, PLAN_REQUIRED, INSUFFICIENT_CREDITS, RATE_LIMITED, VALIDATION_ERROR, WORKFLOW_NOT_AVAILABLE, JOB_NOT_FOUND, PROVIDER_UNAVAILABLE, CHECKOUT_NOT_READY