Importar contenido multimedia desde una URL (transcripción)

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

​

Autenticación y permisos

​

Parámetros

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 4096,
      "format": "uri"
    },
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[^/\\\\\\r\\n\\0]+$"
    },
    "kind": {
      "type": "string",
      "enum": ["transcription", "video_to_srt", "add_subtitles", "animated_captions", "project"]
    },
    "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": ["url", "kind"],
  "additionalProperties": false
}

​

Idempotencia

​

Ejemplos de solicitud

curl --request POST 'https://api.voicecheap.ai/v1/actions/tools_upload_import' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://media.example.com/interview.mp4","filename":"interview.mp4","kind":"transcription","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'

const input = {
  url: 'https://media.example.com/interview.mp4',
  filename: 'interview.mp4',
  kind: 'transcription',
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tools_upload_import', {
  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/tools_upload_import",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"url": "https://media.example.com/interview.mp4", "filename": "interview.mp4", "kind": "transcription", "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": {
    "fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4",
    "fileName": "interview.mp4",
    "fileSize": 1048576,
    "durationSeconds": 60,
    "mimeType": "video/mp4",
    "uploadType": "video",
    "readUrl": "https://media.example.com/uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4"
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

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

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "tools_upload_import",
    "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":"tools_upload_import"}'

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "tools_upload_import",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4",
      "fileName": "interview.mp4",
      "fileSize": 1048576,
      "durationSeconds": 60,
      "mimeType": "video/mp4",
      "uploadType": "video",
      "readUrl": "https://media.example.com/uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4"
    }
  }
}

​

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.
• El prefijo de carga determina el permiso requerido. tools usa transcription:write, subtitles usa subtitles:write, projects usa projects:write y voices usa voices:write.
• Para herramientas, subtítulos y proyectos, kind acepta transcription, video_to_srt, add_subtitles, animated_captions o project. El kind seleccionado determina los límites del flujo de trabajo; el prefijo no fuerza un kind.
• El kind elegido aplica sus propios límites: transcription 200 MiB; video_to_srt y add_subtitles 300 MiB; animated_captions 250 MiB y solo audio; project usa el límite de subida del plan (Beginner 5 GiB, Starter 10 GiB, Creator 20 GiB, Pro 30 GiB, Scale 40 GiB, Enterprise 60 GiB). El contenido multimedia independiente dura como máximo 2 horas. Los subtítulos permiten 30 minutos en Beginner y 60 minutos en los planes públicos superiores, más una tolerancia del contenedor de 2 segundos. La duración del proyecto es de un máximo de 2 horas, o 3 horas en Enterprise.
• Esta acción se ejecuta de forma asíncrona. Consulta periódicamente action_request_get con su nombre de operación y el requestId original hasta que finalice antes de extraer fileKey del resultado.
• Usa una URL HTTPS pública y directa de un archivo de audio o vídeo. Se rechazan las redirecciones, las credenciales, los fragmentos, los puertos distintos de 443 y las direcciones DNS no públicas. Una página de reproducción de YouTube no es una URL multimedia directa; usa las acciones específicas de YouTube.
• filename es opcional cuando la ruta de la URL termina en un nombre de archivo multimedia compatible. El nombre de archivo guardado se sanea. El servidor analiza la duración real antes de devolver un fileKey.
• La importación prepara el contenido multimedia y consume una llamada mensual de integración exitosa; el límite diario de generación de la herramienta solo se consume con la generación posterior.

​

Uso

​

Errores

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