🔌 API StudiosPlay

Integre nossos serviços de IA para música e locução diretamente em suas aplicações. API RESTful simples, poderosa e escalável.

📖 Ver Documentação 🔑 Gerenciar API Keys

🚀 Recursos da API

Tudo que você precisa para integrar IA de música e voz em seus projetos

🎵
Geração de Música

Crie músicas personalizadas com IA usando prompts de texto. Suporte a diversos estilos e gêneros musicais com qualidade profissional.

🎙️
Text-to-Speech

Converta texto em áudio com vozes naturais e expressivas. Múltiplas vozes e idiomas disponíveis com controle de velocidade e tom.

🔄
Speech-to-Speech

Converta áudio de uma voz para outra mantendo a naturalidade e expressividade original. Ideal para dublagem e personalização.

Processamento Rápido

APIs otimizadas com baixa latência. Processamento eficiente para aplicações em tempo real e integração seamless.

🔒
Segurança Avançada

Autenticação via API Key, controle de permissões, rate limiting e logs detalhados para máxima segurança e controle.

📊
Analytics Detalhado

Monitore uso, performance e custos em tempo real através do dashboard administrativo com relatórios completos.

📖 Documentação da API

Referência completa dos endpoints e parâmetros disponíveis

🔑 Autenticação

Todas as requisições devem incluir sua API Key no header. A autenticação é baseada em chaves geradas no painel do usuário:

HTTP Headers
X-API-Key: lk_username_timestamp_hash
Content-Type: application/json

Base URL: https://api.studiosplay.com/v1

Obter API Key: Gerenciar API Keys

Métodos de Autenticação Suportados:

  • Header X-API-Key: Método recomendado
  • Authorization Bearer: Authorization: Bearer YOUR_API_KEY
  • Query Parameter: ?api_key=YOUR_API_KEY (não recomendado para produção)

🎵 Módulo de Música

Gere músicas personalizadas usando inteligência artificial. O sistema suporta diversos estilos musicais e permite controle detalhado sobre a geração.

GET /api/v1/musica/history
Lista o histórico de músicas geradas pelo usuário

Parâmetros de Query:

Parâmetro Tipo Obrigatório Descrição
page integer Opcional Número da página (padrão: 1)
per_page integer Opcional Itens por página (padrão: 20, máximo: 50)
POST /api/v1/musica/generate
Gera uma nova música baseada no prompt fornecido

Parâmetros do Body (JSON):

Parâmetro Tipo Obrigatório Descrição
prompt string Obrigatório Descrição da música desejada (máximo 1000 caracteres)
model string Opcional Modelo de IA a usar (padrão: "chirp-v3-5")
Exemplo de Requisição
curl -X POST "https://api.studiosplay.com/v1/musica/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lk_username_timestamp_hash" \
  -d '{
    "prompt": "Uma música alegre de samba com guitarra e percussão",
    "model": "chirp-v3-5"
  }'
GET /api/v1/musica/{id}
Obtém detalhes de uma música específica
GET /api/v1/musica/status/{taskId}
Verifica o status de geração de uma música
DELETE /api/v1/musica/{id}
Remove uma música do histórico

Resposta de Sucesso (Geração):

JSON Response
{
  "success": true,
  "data": {
    "task_id": "task_abc123",
    "status": "processing",
    "message": "Música sendo gerada. Use o task_id para verificar o status.",
    "estimated_time": "60-120 segundos"
  },
  "message": "Música gerada com sucesso",
  "timestamp": "2025-06-19T10:30:00Z",
  "request_id": "req_xyz789"
}

🎙️ Módulo de Clone de Voz

Converta texto em fala (TTS) e transforme áudio de uma voz para outra (STS) usando vozes do sistema ou personalizadas.

GET /api/v1/clone_voz/voices
Lista todas as vozes disponíveis (sistema + personalizadas)

Resposta - Vozes Disponíveis:

JSON Response
{
  "success": true,
  "data": [
    {
      "id": "alloy",
      "name": "Alloy",
      "type": "system",
      "language": "pt-BR",
      "gender": "neutral",
      "description": "Voz neutra e clara"
    },
    {
      "id": "nova",
      "name": "Nova",
      "type": "system",
      "language": "pt-BR",
      "gender": "female",
      "description": "Voz feminina moderna"
    }
  ]
}
POST /api/v1/clone_voz/tts
Gera áudio TTS a partir de texto

Parâmetros do Body (JSON):

Parâmetro Tipo Obrigatório Descrição
text string Obrigatório Texto a ser convertido em áudio (máximo 5000 caracteres)
voice_id string Obrigatório ID da voz a ser utilizada
speed float Opcional Velocidade da fala (0.5 a 2.0, padrão: 1.0)
pitch float Opcional Tom da voz (0.5 a 2.0, padrão: 1.0)
POST /api/v1/clone_voz/sts
Converte áudio de uma voz para outra (Speech-to-Speech)

Parâmetros (Multipart Form):

Parâmetro Tipo Obrigatório Descrição
audio file Obrigatório Arquivo de áudio (MP3, WAV - máximo 10MB)
voice_id string Obrigatório ID da voz de destino
GET /api/v1/clone_voz/history
Lista histórico de TTS e STS

Parâmetros de Query:

Parâmetro Tipo Obrigatório Descrição
type string Opcional Filtrar por tipo: "tts" ou "sts"
page integer Opcional Número da página (padrão: 1)
per_page integer Opcional Itens por página (padrão: 20, máximo: 50)

👤 Informações do Usuário

Endpoints para obter informações sobre o usuário autenticado, incluindo saldo de créditos e estatísticas de uso.

GET /api/v1/user/info
Obtém informações completas do usuário

Resposta de Sucesso:

JSON Response
{
  "success": true,
  "data": {
    "username": "usuario_exemplo",
    "credits": 45.50,
    "music_limit": 10,
    "music_count": 3,
    "char_limit": 10000
  },
  "message": "Informações do usuário obtidas com sucesso",
  "timestamp": "2025-06-19T10:30:00Z",
  "request_id": "req_abc123"
}
GET /api/v1/status
Verifica o status da API (não requer autenticação)

Resposta - Status da API:

JSON Response
{
  "success": true,
  "data": {
    "status": "online",
    "version": "1.0.0",
    "timestamp": "2025-06-19T10:30:00Z",
    "modules": ["musica", "clone_voz"]
  },
  "message": "API StudiosPlay está funcionando",
  "timestamp": "2025-06-19T10:30:00Z",
  "request_id": "req_status123"
}

💡 Exemplos Práticos

Exemplo 1: Gerar Música com JavaScript

JavaScript
const apiKey = 'lk_username_timestamp_hash';
const baseUrl = 'https://api.studiosplay.com/v1';

async function gerarMusica(prompt) {
  try {
    const response = await fetch(`${baseUrl}/musica/generate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({
        prompt: prompt,
        model: 'chirp-v3-5'
      })
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log('Música sendo gerada:', data.data.task_id);
      return data.data.task_id;
    } else {
      console.error('Erro:', data.error.message);
    }
  } catch (error) {
    console.error('Erro na requisição:', error);
  }
}

// Usar a função
gerarMusica('Uma música relaxante de jazz com piano');

Exemplo 2: TTS com Python

Python
import requests
import json

API_KEY = 'lk_username_timestamp_hash'
BASE_URL = 'https://api.studiosplay.com/v1'

def gerar_tts(texto, voice_id='alloy'):
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    
    data = {
        'text': texto,
        'voice_id': voice_id,
        'speed': 1.0,
        'pitch': 1.0
    }
    
    response = requests.post(
        f'{BASE_URL}/clone_voz/tts',
        headers=headers,
        json=data
    )
    
    if response.status_code == 201:
        result = response.json()
        if result['success']:
            print(f"TTS gerado: {result['data']['audio_url']}")
            return result['data']
        else:
            print(f"Erro: {result['error']['message']}")
    else:
        print(f"Erro HTTP: {response.status_code}")

# Usar a função
gerar_tts("Olá, este é um teste de TTS do StudiosPlay!", "nova")

Exemplo 3: Verificar Status com PHP

PHP

⚠️ Códigos de Erro

Lista completa dos códigos de erro que podem ser retornados pela API:

Erros de Autenticação (4xx):

Código HTTP Descrição Solução
UNAUTHORIZED 401 API Key inválida ou inativa Verificar se a API Key está correta e ativa
INSUFFICIENT_CREDITS 402 Créditos insuficientes Recarregar créditos na conta
PERMISSION_DENIED 403 Usuário sem permissão para o módulo Verificar permissões da conta
MUSIC_LIMIT_EXCEEDED 403 Limite de músicas excedido Aguardar renovação ou upgrade do plano

Erros de Validação (400):

Código Descrição Solução
INVALID_INPUT Dados de entrada inválidos Verificar formato JSON e campos obrigatórios
MISSING_PROMPT Prompt é obrigatório Incluir campo 'prompt' na requisição
MISSING_TEXT Texto é obrigatório Incluir campo 'text' na requisição
MISSING_VOICE ID da voz é obrigatório Incluir campo 'voice_id' na requisição
MISSING_AUDIO Arquivo de áudio é obrigatório Incluir arquivo de áudio na requisição
PROMPT_TOO_LONG Prompt muito longo Reduzir prompt para máximo 1000 caracteres
TEXT_TOO_LONG Texto muito longo Reduzir texto para máximo 5000 caracteres
FILE_TOO_LARGE Arquivo muito grande Reduzir tamanho do arquivo para máximo 10MB
INVALID_FILE_TYPE Tipo de arquivo não suportado Usar apenas MP3 ou WAV

Erros do Servidor (5xx):

Código HTTP Descrição Solução
INTERNAL_ERROR 500 Erro interno do servidor Tentar novamente ou contatar suporte
GENERATION_ERROR 500 Erro na geração de música Tentar novamente com prompt diferente
TTS_ERROR 500 Erro na geração de TTS Tentar novamente ou verificar texto
STS_ERROR 500 Erro na conversão STS Verificar qualidade do áudio de entrada

Exemplo de Resposta de Erro:

JSON Error Response
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Créditos insuficientes para esta operação",
    "details": {
      "required": 1.0,
      "available": 0.5
    }
  },
  "timestamp": "2025-06-19T10:30:00Z",
  "request_id": "req_error123"
}

📊 Rate Limiting

Limites de Requisições

Para garantir a qualidade do serviço, aplicamos os seguintes limites:

  • 100 requisições por minuto por API Key
  • Janela deslizante de 60 segundos
  • Headers de resposta informativos:
    • X-RateLimit-Limit: Limite total
    • X-RateLimit-Remaining: Requisições restantes
    • X-RateLimit-Reset: Timestamp do reset

Resposta quando limite é excedido:

HTTP 429 - Too Many Requests
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Muitas requisições. Tente novamente em alguns segundos.",
    "details": {
      "retry_after": 30
    }
  }
}

🔧 SDKs e Bibliotecas

🟨
JavaScript/Node.js

SDK oficial para JavaScript com suporte a TypeScript. Ideal para aplicações web e Node.js.

npm install studiosplay-sdk
🐍
Python

Biblioteca Python com suporte a async/await. Perfeita para aplicações de machine learning e automação.

pip install studiosplay
🐘
PHP

SDK PHP com suporte a Composer. Integração simples para aplicações web PHP.

composer require studiosplay/sdk