> ## 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. # Consultar resultado de capítulos do YouTube > Leia um dos seus resultados salvos de capítulos do YouTube, incluindo seu texto de saída ou URL de mídia. Leia um dos seus resultados salvos de capítulos do YouTube, incluindo seu texto de saída ou URL de mídia. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/youtube_chapters_history_get ``` ## Autenticação e permissões 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. Permissões necessárias: `transcription: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 Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 160. Padrão: `^[A-Za-z0-9_-]+$`. 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": { "historyId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": ["historyId"], "additionalProperties": false } ``` ## 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. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/youtube_chapters_history_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"historyId":"history_20261016_001"}' ``` ```javascript JavaScript theme={null} const input = { historyId: 'history_20261016_001', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/youtube_chapters_history_get', { 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/youtube_chapters_history_get", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"historyId": "history_20261016_001"}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## 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. O item completo do histórico de capítulos do YouTube pertencente ao usuário executor, incluindo seu conteúdo de saída. ```json HTTP 200 theme={null} { "data": { "historyId": "history_20261016_001", "youtubeUrl": "https://www.youtube.com/watch?v=abcdefghijk", "videoId": "abcdefghijk", "videoTitle": "Product tutorial", "channelName": "Example channel", "language": "en", "durationSeconds": 60, "durationMinutes": 1, "createdAt": 1792152000000, "updatedAt": 1792152000000, "status": "success", "chapterCount": 3, "response": { "language": "en", "video": { "videoId": "abcdefghijk", "sourceUrl": "https://www.youtube.com/watch?v=abcdefghijk", "canonicalUrl": "https://www.youtube.com/watch?v=abcdefghijk", "title": "Product tutorial", "channelName": "Example channel", "durationSeconds": 60 }, "chapters": [ { "startSeconds": 0, "timestamp": "00:00", "title": "Introduction" }, { "startSeconds": 20, "timestamp": "00:20", "title": "Create a project" }, { "startSeconds": 40, "timestamp": "00:40", "title": "Export your result" } ], "text": "00:00 Introduction\n00:20 Create a project\n00:40 Export your result", "createdAt": 1792152000000 } } } ``` ## Campos do resultado | Campo | Descrição | | - | - | | `data.historyId` | ID do item de histórico de ferramenta web pertencente à conta. | | `data.createdAt` | Timestamp Unix em milissegundos. | | `data.updatedAt` | Timestamp Unix em milissegundos. | | `data.response` | Resposta completa salva da ferramenta do YouTube, incluindo metadados do vídeo e texto gerado. | | `data.response.chapters` | Entradas de capítulos com startSeconds, timestamp e title. | | `data.response.text` | Texto de capítulos com marcação de tempo. | | `data.chapterCount` | Número de capítulos salvos. | ## Notas da operação * Requer uma assinatura paga e a permissão da ação. O plano pessoal de ferramentas do usuário executor é verificado novamente na execução; as ferramentas salvas e as referências de envio pertencem a esse usuário, inclusive quando a credencial está associada a uma equipe. * Uma ação bem-sucedida usa uma chamada mensal compartilhada de API/MCP. Beginner permite 500, Starter 5,000 e Creator 25,000 chamadas/mês; Pro, Scale e Enterprise não têm teto mensal. Os limites por minuto ainda se aplicam: 30, 60, 120, 180, 300 e 600, respectivamente. As cotas de geração das ferramentas são separadas. * historyId deve ser obtido do history\_list correspondente pertencente ao ator ou de uma geração bem-sucedida. IDs de outro usuário ou de outra coleção de histórico não concedem acesso. * Esta leitura retorna o histórico completo salvo da ferramenta, não um resultId durável da integração. Ela não gera novamente, não consome um upload nem usa uma geração diária da ferramenta. * response contém entradas de capítulos com startSeconds numérico, timestamp formatado e title, além de texto pronto para colar na descrição de um vídeo. ## 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` | Os argumentos não atendem ao esquema da ação ou um argumento desconhecido foi fornecido. | | 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` | A chave de API ou a conexão MCP não tem a permissão necessária para a ação. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. | | 403 | `PAID_SUBSCRIPTION_REQUIRED` | O ator autenticado não tem mais uma assinatura paga quando esta ação da ferramenta é executada. | | 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. | | 404 | `YOUTUBE_CHAPTERS_HISTORY_NOT_FOUND` | O histórico de capítulos do YouTube solicitado não foi encontrado para este usuário executor. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | As chamadas usadas e pendentes atingiram a cota mensal compartilhada de API/MCP. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | A conta atingiu seu limite de integração por minuto; inspecione retryAfterSeconds. | | 500 | `INTERNAL_ERROR` | Não foi possível ler o conteúdo do histórico salvo. | | 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": ["transcription:read"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.