Crear capítulos de YouTube

POST https://api.voicecheap.ai/v1/actions/youtube_chapters_create

​

Autenticación y permisos

​

Parámetros

{
  "type": "object",
  "properties": {
    "youtubeUrl": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "requestId": {
      "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
      "type": "string",
      "format": "uuid",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    }
  },
  "required": ["youtubeUrl"],
  "additionalProperties": false
}

​

Idempotencia

​

Ejemplos de solicitud

curl --request POST 'https://api.voicecheap.ai/v1/actions/youtube_chapters_create' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"youtubeUrl":"https://www.youtube.com/watch?v=abcdefghijk","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'

const input = {
  youtubeUrl: 'https://www.youtube.com/watch?v=abcdefghijk',
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/youtube_chapters_create', {
  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);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/youtube_chapters_create",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"youtubeUrl": "https://www.youtube.com/watch?v=abcdefghijk", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

​

Respuesta

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "data": {
    "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
    "operation": "youtube_chapters_create",
    "createdAt": 1792152000000,
    "fileName": "voicecheap-youtube_chapters_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
    "byteLength": 603,
    "contentType": "application/json; charset=utf-8",
    "status": "completed",
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "getAction": "transcription_result_get",
    "downloadAction": "transcription_result_download",
    "listAction": "transcription_result_list"
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "youtube_chapters_create",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "youtube_chapters_create",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

​

Campos del resultado

​

Recuperar y consultar esta solicitud

curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab","operation":"youtube_chapters_create"}'

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "youtube_chapters_create",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
      "operation": "youtube_chapters_create",
      "createdAt": 1792152000000,
      "fileName": "voicecheap-youtube_chapters_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
      "byteLength": 603,
      "contentType": "application/json; charset=utf-8",
      "status": "completed",
      "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
      "getAction": "transcription_result_get",
      "downloadAction": "transcription_result_download",
      "listAction": "transcription_result_list"
    }
  }
}

​

Notas de la operación

• Requiere una suscripción de pago y el permiso de la acción. El plan personal de herramientas del actor se comprueba de nuevo al ejecutar; las herramientas guardadas y las referencias de carga pertenecen a ese actor, también cuando la credencial está asociada a un equipo.
• Una acción correcta consume una llamada mensual compartida de API/MCP. Beginner permite 500, Starter 5,000 y Creator 25,000 llamadas al mes; Pro, Scale y Enterprise no tienen límite mensual. Siguen aplicándose los límites por minuto: 30, 60, 120, 180, 300 y 600, respectivamente. Las cuotas de generación de las herramientas son independientes.
• Usa un requestId UUID v4 o un encabezado Idempotency-Key idéntico, y conserva la misma acción, el mismo ID y los mismos argumentos en los reintentos. Una repetición desde la caché no consume otra llamada mensual.
• Esta es una acción asíncrona. El resultado inicial del transporte es una solicitud en ejecución con pollAction; consulta periódicamente action_request_get con esta operación y el requestId original. El resultado de la operación completada que se muestra aquí es una referencia compacta a la salida guardada, no el cuerpo generado.
• El resultado completo se guarda con la titularidad autenticada en almacenamiento cifrado, independientemente de la caché limitada de consulta de acciones. Llama al getAction devuelto con resultId e includeContent: true para obtener JSON estructurado, o a downloadAction con resultId para obtener texto JSON. listAction permite recuperarlo cuando solo se conoce la solicitud original.
• El JSON guardado está limitado a 32 MiB. Los metadatos nunca exponen su clave de cifrado de almacenamiento ni una URL de descarga de la transcripción sin autenticación.
• Una generación correcta consume una unidad de la cuota personal de la herramienta. Una generación fallida normalmente libera su reserva de herramienta. Cuando no se sabe con certeza si la salida se ha guardado, revisa la misma solicitud y el historial de resultados guardados antes de volver a generar; el servidor mantiene la reserva para evitar un consumo duplicado.
• Los planes superiores sin límite mensual de integración siguen teniendo las cuotas diarias específicas de cada herramienta y los límites multimedia que se indican a continuación. Estas acciones independientes consumen su cuota de herramienta en lugar de minutos de doblaje o caracteres TTS.
• Usa una URL HTTPS pública de un vídeo de YouTube. El vídeo debe durar al menos 30 segundos y como máximo 2 horas.
• Límite diario de capítulos de YouTube: Beginner 5, Starter 10, Creator 20, Pro 35, Scale 50 y Enterprise 100; compartido con la herramienta web de capítulos.
• La cuota de capítulos se reserva de inmediato y se compensa ante un fallo de ejecución normal. Una salida correcta sigue contabilizada aunque se pierda la confirmación de liquidación.
• generationId es el ID del historial de la herramienta cuando su intento de guardar el historial tiene éxito. El resultId específico de la integración sigue siendo el identificador de recuperación que pertenece a la cuenta.
• Los capítulos incluyen una cadena de marca de tiempo y un startSeconds numérico. No se usa ningún fileKey de origen cargado previamente.

​

Uso

​

Errores

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["transcription:write"]
  }
}