> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar falas geradas

> Liste seu histórico de falas, das mais recentes para as mais antigas. Passe nextCursor como cursor para recuperar criações mais antigas.

Liste seu histórico de falas, das mais recentes para as mais antigas. Passe nextCursor como cursor para recuperar criações mais antigas.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/tts_list
```

## Autenticação e permissões

<ParamField header="x-api-key" type="string" required>
  Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são
  aceitos apenas pelo MCP, não por este endpoint REST.
</ParamField>

Permissões necessárias: `tts:read`.

É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.

## Parâmetros

<ParamField body="limit" type="integer">
  Valor inteiro.

  Mínimo: 1. Máximo: 100. Valor padrão: 30.
</ParamField>

<ParamField body="cursor" type="string">
  ID do histórico retornado por tts\_generate ou tts\_list.

  Padrão: `^(free-)?[0-9a-f]{64}$`.
</ParamField>

<Accordion title="Esquema de entrada completo">
  O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "limit": {
        "default": 30,
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "cursor": {
        "type": "string",
        "pattern": "^(free-)?[0-9a-f]{64}$",
        "description": "History ID returned by tts_generate or tts_list."
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Exemplos de requisição

Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_list' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"limit":1}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    limit: 1,
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_list', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VOICECHEAP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.code + ': ' + body.message);
  console.log(body);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.voicecheap.ai/v1/actions/tts_list",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"limit": 1},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## Resposta

Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais.

Página de resumos do histórico de fala, dos mais recentes aos mais antigos, e o cursor para solicitar criações anteriores.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "items": [
        {
          "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
          "textPreview": "Hello world.",
          "voice": "933563129e564b19a115bedd57b7406a",
          "voiceName": "Sarah",
          "voiceSource": "catalog",
          "inputType": "text",
          "instructionPreset": "narrator",
          "sourceFileName": "launch-script.txt",
          "characterCount": 12,
          "durationSeconds": 1.5,
          "isPreview": false,
          "createdAt": 1792152000000,
          "updatedAt": 1792152000000,
          "status": "success"
        }
      ],
      "nextCursor": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"
    }
  }
  ```
</ResponseExample>

## Campos do resultado

| Campo | Descrição |
| - | - |
| `data.items` | Resumos do histórico de fala, dos mais recentes aos mais antigos. |
| `data.items[].historyId` | ID do histórico de fala pertencente ao usuário: 64 caracteres hexadecimais minúsculos, opcionalmente com o prefixo free- para uma prévia do aplicativo. |
| `data.items[].voice` | O ID original de seleção TTS, incluindo clone:\<UUID> para uma voz personalizada salva. |
| `data.items[].voiceName` | Nome de exibição salvo opcional da voz selecionada. |
| `data.items[].voiceSource` | Origem opcional da voz: catalog ou clone. |
| `data.items[].inputType` | Tipo de entrada original: text ou pdf. |
| `data.items[].instructionPreset` | Predefinição de entrega armazenada. |
| `data.items[].sourceFileName` | Nome opcional do arquivo original fornecido na geração. |
| `data.items[].characterCount` | Contagem de caracteres registrada para esta criação de fala. |
| `data.items[].durationSeconds` | Duração do áudio em segundos. |
| `data.items[].createdAt` | Horário de criação como um timestamp Unix em milissegundos. |
| `data.items[].updatedAt` | Horário da última atualização como uma marcação de tempo Unix em milissegundos. |
| `data.items[].status` | Itens de fala armazenados com sucesso usam success; tts\_generate usa completed no resultado da geração. |
| `data.items[].textPreview` | Primeiros 180 caracteres do roteiro armazenado. |
| `data.items[].isPreview` | true enquanto o áudio contém apenas uma prévia do roteiro armazenado. |
| `data.nextCursor` | historyId do último item de uma página cheia; caso contrário, null. |

## Notas da operação

* limit tem 30 como padrão e varia de 1 a 100. Passe o nextCursor retornado como cursor para a página seguinte.
* nextCursor é null quando são retornados menos de limit itens. Uma última página cheia ainda pode retornar um cursor; a próxima chamada pode estar vazia.
* Cada textPreview contém no máximo os primeiros 180 caracteres. Use tts\_get para obter o roteiro completo e a URL do áudio.
* Os itens de histórico informam status: success. Isso difere de status: completed em um resultado de geração de fala.
* O histórico de fala e as vozes personalizadas pertencem à conta autenticada. O faturamento da equipe não concede acesso à fala nem às vozes de outro membro.

## Uso

Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.

## Erros

| Status HTTP | Código | Significado ou recuperação |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Foram fornecidas credenciais em um parâmetro de consulta access\_token ou api\_key. Envie as credenciais nos cabeçalhos. |
| 400 | `VALIDATION_ERROR` | A entrada não corresponde ao esquema da ação; inspecione details para ver os erros dos campos. |
| 401 | `API_KEY_EXPIRED` | A chave de API expirou. |
| 401 | `INVALID_API_KEY` | Forneça uma chave de API válida e dentro do prazo de validade. |
| 401 | `INVALID_CREDENTIAL` | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. |
| 401 | `USER_NOT_FOUND` | A conta da credencial não existe mais. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. |
| 403 | `INSUFFICIENT_SCOPE` | Conceda todas as permissões necessárias ou escolha outra credencial. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Aguarde a renovação do limite mensal ou mude de plano. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. |
| 500 | `INTERNAL_ERROR` | Verifique o estado da requisição salva e o histórico do recurso antes de decidir repetir uma alteração. |
| 503 | `SERVER_RESTARTING` | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["tts:read"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.