Começando

Use a API HTTP do PolyLingo para traduzir texto simples, Markdown, JSON ou HTML mantendo a estrutura intacta. Este guia cobre o endpoint de produção, autenticação e sua primeira requisição bem-sucedida.

URL Base

Todos os exemplos usam a API de produção:

Todo caminho abaixo é relativo a essa base (por exemplo, POST /translate significa POST https://api.usepolylingo.com/v1/translate).

Se você executar sua própria instância da API PolyLingo, substitua o host pela URL do seu deployment e mantenha o prefixo /v1 a menos que tenha configurado de outra forma.

Autenticação

Endpoints protegidos esperam sua chave API no cabeçalho Authorization:

Authorization: Bearer <your_api_key>

Obtendo uma chave: Crie uma no app PolyLingo em API keys. Você verá a chave completa apenas uma vez—armazene-a em local seguro (variável de ambiente ou gerenciador de segredos). Chaves podem ser revogadas na mesma tela.

Segurança: Trate a chave como uma senha. Prefira chamar a API do seu servidor, não do código público do navegador, para que a chave nunca seja exposta aos usuários.

Se o cabeçalho estiver ausente, incorreto, ou a chave inválida ou revogada, a API responde com 401 e error: "invalid_api_key".

Endpoints e chaves

Primeira requisição (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

Uma resposta bem-sucedida inclui um objeto translations (uma entrada por idioma alvo solicitado) e um objeto usage com contagem de tokens.

Primeira requisição (Node.js)

Node.js 18+ inclui fetch:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

Verifique se a API está acessível

Nenhuma chave é necessária para health:

curl -sS "https://api.usepolylingo.com/v1/health"

Você deve ver um pequeno payload JSON indicando que o serviço está ativo. Use GET /languages para a lista de códigos que pode passar como targets.

CORS e apps de navegador

A API pode restringir quais origens de navegador podem chamá-la diretamente, para que chaves não sejam usadas de sites não confiáveis. Chamadas do lado servidor (Node, Python, funções edge, seu backend) não são limitadas por CORS.

Para um app de página única, o padrão usual é: seu frontend conversa com seu backend, e seu backend chama PolyLingo com a chave API.

Próximos passos

• Referência da API — formatos de requisição e resposta, erros e limites.