Foleyix · API v1

Documentação API

Gere WAV privados pelo seu servidor com a assinatura Foleyix.

Regras de integração

Creator, Studio e Ultra incluem API. Site, CLI e API compartilham segundos, armazenamento e fila.

Ao vencer, novas gerações e chaves são bloqueadas. Tarefas existentes continuam e o áudio retido pode ser baixado; renovar restaura a geração.

Apenas integração de servidor. Sem chamadas de navegador entre origens, webhooks, vozes de referência ou projetos profissionais.

Autenticação

Authorization: Bearer <API_KEY>

Salve esta chave agora. Ela só será exibida uma vez. Mantenha-a no servidor e nunca a publique.

https://foleyix.com/api/v1

Enviar → consultar → baixar

Envie uma Idempotency-Key única (1–128 caracteres) por geração. Tente novamente com a mesma chave e entrada, mesmo após rotação; entrada diferente retorna 409.

Consulte em intervalos de pelo menos 5 segundos. queued/running estão em andamento; succeeded/failed/unknown encerram a consulta. Timeout ou unknown não autoriza recriar automaticamente a tarefa.

curl --fail-with-body https://foleyix.com/api/v1/generations \
  -H "Authorization: Bearer $FOLEYIX_API_KEY" \
  -H "Idempotency-Key: my-audio-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A quiet forest with birds singing, 3 seconds.","mode":"ambience"}'

curl ↓Node.js ↓Python ↓

Endpoint

Endpoint	Comportamento
`POST /generations`	Enviar prompt e modo opcional; retorna tarefa com HTTP 202.
`GET /jobs`	Listar suas tarefas independentes com cursor, limit e active=1.
`GET /jobs/{id}`	Consultar estado, duração real, retenção e disponibilidade.
`GET /jobs/{id}/audio`	Baixar WAV com GET, HEAD e um único intervalo de bytes.
`GET /quota`	Consultar segundos, armazenamento, fila e permissão atual.

cursor · limit: 1–100 (50) · active: 0 | 1

Modos de geração

free · narration · dialogue · podcast · scene · sfx · ambience

Use 1–3.000 caracteres Unicode. O modo padrão é free; escolher um modo não altera seu prompt.

Cota compartilhada

Creator, Studio e Ultra incluem API. Site, CLI e API compartilham segundos, armazenamento e fila.

GET /api/v1/quota
quota.generationLimit / generationUsed / generationReserved
quota.availableGenerationSeconds / generationAllowed
quota.storageLimit / storageUsed
quota.queueUsed / queueLimit

Limites de solicitações

Até 300 solicitações e 20 envios de geração por minuto por conta, compartilhados entre todas as chaves.

429 · Retry-After: seconds

Até 5 chaves ativas por conta.

Erros e estados

{"error":{"code":"paid_subscription_required","message":"…"},"requestId":"…"}
X-Request-ID: …
400 invalid_input · 401 invalid_api_key · 403 paid_subscription_required
404 job_not_found · 409 request_key_conflict / result_not_ready
410 audio_expired · 429 rate_limited · 503 api_unavailable

Consulte em intervalos de pelo menos 5 segundos. queued/running estão em andamento; succeeded/failed/unknown encerram a consulta. Timeout ou unknown não autoriza recriar automaticamente a tarefa.

Downloads WAV privados

Baixar WAV com GET, HEAD e um único intervalo de bytes.

Downloads também exigem autenticação Bearer. A URL é privada, expira com a retenção e nunca redireciona a um link público do provedor.

GET /api/v1/jobs/{id}/audio
Authorization: Bearer <API_KEY>
Range: bytes=0-43

job.durationSeconds / bytes / resultAvailable
job.resultExpiresAt / downloadUrl

Ao vencer, novas gerações e chaves são bloqueadas. Tarefas existentes continuam e o áudio retido pode ser baixado; renovar restaura a geração.

Salve esta chave agora. Ela só será exibida uma vez. Mantenha-a no servidor e nunca a publique.