heartmula/transcribe/speech-to-textO HeartMuLa Transcribe é um endpoint de speech-to-text multilíngue ajustado para vocais cantados: envie a URL de um áudio e receba a letra em texto. Não há opções, e não são devolvidos tempos por linha, valores de confiança nem rótulos de falante.
Os exemplos usam as definições públicas de parâmetros do endpoint selecionado. Troque a chave de API e as mídias de exemplo e envie a requisição a partir do seu servidor.
SDKs e integraçõeshttps://api.spicyapi.ai/api/v1/jobs/createTaskGuarde a chave de API na variável de ambiente do servidor SPICY_API_KEY. Use autenticação Bearer e Content-Type: application/json nas requisições JSON.
Authorization: Bearer $SPICY_API_KEY# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heartmula/transcribe/speech-to-text",
"input": {
"audio_url": "https://example.com/reference.mp3"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"Gerado a partir do schema de entrada deste modelo — o mesmo que a API usa para validar cada requisição.
Coloque estes campos no objeto input do corpo da requisição. Nomes e tipos são os mesmos da API. Quando nenhum valor padrão estiver indicado, não presuma que exista um.
audio_urlstringObrigatórioUma URL que resolve direto para um arquivo de áudio. Páginas que devolvem HTML falham como material inválido. Nenhuma dica de idioma é necessária nem aceita: o modelo é multilíngue e tira isso do próprio áudio.
{
"additionalProperties": false,
"properties": {
"audio_url": {
"contentMediaType": [
"audio/mpeg",
"audio/wav"
],
"description": "URL of the audio file to transcribe. Must resolve directly to audio, not to a web page.",
"format": "uri",
"minLength": 1,
"type": "string",
"x-ui": {
"order": 100,
"primary": true,
"widget": "upload"
}
}
},
"required": [
"audio_url"
],
"type": "object",
"x-pricing": {
"billingMode": "per_unit",
"variantFields": []
}
}HTTP 202 quer dizer que a tarefa foi aceita, não que terminou. Guarde o taskId devolvido e consulte essa tarefa. Não crie outra enquanto espera o resultado.
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}A resposta de aceitação já traz a estimativa, para que o seu aplicativo mostre o mesmo valor no histórico de tarefas e na cobrança.
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
--data-urlencode "taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"Comece consultando a cada 2 segundos, mais ou menos, e vá espaçando. Pare em um estado final. Se a conexão cair, consulte o taskId original. Só recrie a tarefa com a chave de idempotência e o corpo originais.
import { verifyWebhook } from "@spicyapi/sdk";
// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
const { payload } = verifyWebhook({
rawBody: req.body,
timestamp: req.header("X-Webhook-Timestamp"),
signature: req.header("X-Webhook-Signature"),
payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
secret: process.env.SPICY_WEBHOOK_SECRET,
});
res.status(200).end();
void handleFinishedTask(payload);
});Passe callBackUrl ao criar a tarefa e o registro concluído chega até você via POST — sem nenhum laço de polling. Toda entrega traz X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Payload-Version. A assinatura é um HMAC-SHA256 em base64 sobre taskId.timestamp.sha256(body), então confira contra os bytes brutos: se você analisar o JSON e serializar de novo, os bytes mudam e a verificação falha. Entregas com erro são repetidas, ou seja, o mesmo taskId pode chegar duas vezes — deixe seu handler idempotente. Responda 2xx primeiro e faça o trabalho depois; um handler lento conta como entrega falha.
Só consuma output quando state for succeeded. Em caso de falha, use errorCode, errorMessage e request_id para investigar. Os custos e estados de exemplo não representam uma cobrança real.
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "heartmula/transcribe/speech-to-text",
"state": "succeeded",
"output": {
"text": "…"
},
"cost": "0.750000",
"settled": true,
"createdAt": "2026-08-28T12:00:00Z",
"completedAt": "2026-08-28T12:00:30Z"
}
}Para cada arquivo disponível, abra ou baixe assets[].url direto, sem o cabeçalho Authorization da API. O link assinado expira em expiresAt: consulte a tarefa de novo para renovar enquanto o arquivo estiver dentro do prazo de retenção. Arquivo pendente ou indisponível não tem URL. Trate os links assinados como dado privado.
Use a SpicyAPI no seu app, terminal, assistente de IA ou fluxo visual. Escolha um guia de configuração.
Você não precisa escrever nada do código acima. Conecte o servidor MCP uma vez e qualquer agente que fale MCP — Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, Cline, LibreChat — chama este modelo pelo nome. Ou rode direto do terminal, em um comando só.
Com heartmula/transcribe/speech-to-text, gere o retrato de uma dançarina sob luz de neon e salve em ./out/.
O agente procura o modelo no catálogo atual e envia o arquivo local por você. Em seguida, mostra a estimativa exata de preço e o valor máximo de cobrança e espera sua confirmação. Nada é cobrado até você autorizar.
claude mcp add spicyapi -e SPICY_API_KEY=$SPICY_API_KEY \
-- npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx skills add spicyapi-ai/spicy-skillA primeira linha entrega as ferramentas ao agente; a segunda, a Skill com as regras de uso: mostrar a estimativa antes de cobrar, enviar arquivos locais em vez de colar bytes e ler a URL do arquivo concluído em vez de adivinhá-la. Os demais clientes usam o mesmo servidor pelo próprio arquivo de configuração: veja a área do desenvolvedor.
npx @spicyapi/cli tasks create --model heartmula/transcribe/speech-to-text \
--input-json '{"audio_url":"https://example.com/reference.mp3"}' \
--waitA entrada vem do schema deste endpoint, igual aos exemplos acima. --wait acompanha a tarefa até o fim e imprime o resultado; use --yes para pular a confirmação na CI. Defina antes o SPICY_API_KEY — a mesma chave serve para a API, a CLI e o servidor MCP.
npx @spicyapi/cli files upload ./poster.png
# -> spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3
npx @spicyapi/cli tasks create --model heartmula/transcribe/speech-to-text \
--input-json '{"audio_url":"spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3"}' \
--waitA requisição aceita URLs, não bytes. Envie o arquivo primeiro e passe o URI spicy:// que ele imprime — o nome do campo acima vem do schema deste endpoint. Um agente pelo MCP faz esse passo por você, e é por isso que a frase lá em cima pode citar ./poster.png direto. Mídia já acessível por HTTPS público dispensa upload.
npx @spicyapi/cli tasks create --model heartmula/transcribe/speech-to-text \
--input-json '{…}' --retention 1h --wait
npx @spicyapi/cli tasks get $TASK_ID # read back the retention that appliedO --retention só encurta o prazo — 30m, 1h, 7d, ou 0 para apagar assim que a tarefa chega a um estado final. O valor que realmente vale é o menor entre a sua requisição, as configurações da conta e o limite da plataforma; então releia do registro da tarefa em vez de supor que o número pedido valeu. Pedir um prazo maior do que a conta permite não faz nada.
Instale os nós da SpicyAPI pelo ComfyUI Manager ou com o comando abaixo e procure por HeartMuLa Transcribe · Transcribe Lyrics no canvas. O nó tem as mesmas opções desta página e mostra o preço antes da execução.
cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapiO painel incorporado lê o mesmo schema desta página, então não tem como sair de sincronia com a API. Se a sua documentação precisar de conteúdo indexável, pegue o JSON em /api/embed/models/ e renderize por conta própria.
<iframe src="https://spicyapi.ai/embed/pt-BR/models/heartmula-transcribe/api?model=heartmula%2Ftranscribe%2Fspeech-to-text" width="100%" height="560" loading="lazy" title="Exemplo de requisição" style="border:1px solid rgba(0,0,0,.12)"></iframe>