Importa contenuti multimediali da un URL (progetti)

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

​

Autenticazione e autorizzazioni

​

Parametri

{
  "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
}

​

Idempotenza

​

Esempi di richiesta

curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_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":"project","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'

const input = {
  url: 'https://media.example.com/interview.mp4',
  filename: 'interview.mp4',
  kind: 'project',
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_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/projects_upload_import",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"url": "https://media.example.com/interview.mp4", "filename": "interview.mp4", "kind": "project", "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)

​

Risposta

{
  "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": "projects_upload_import",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

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

​

Campi del risultato

​

Recupera e monitora questa richiesta

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":"projects_upload_import"}'

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

​

Note sull’operazione

• Richiede un abbonamento a pagamento e l’autorizzazione dell’azione. Il piano personale del chiamante per gli strumenti viene ricontrollato al momento dell’esecuzione; gli strumenti salvati e i riferimenti ai caricamenti appartengono a quel chiamante, anche quando la credenziale è associata a un team.
• Un’azione riuscita consuma una chiamata mensile condivisa API/MCP. Beginner consente 500, Starter 5,000 e Creator 25,000 chiamate al mese; Pro, Scale ed Enterprise non hanno un limite mensile. Si applicano comunque i limiti al minuto: rispettivamente 30, 60, 120, 180, 300 e 600. Le quote di generazione degli strumenti sono separate.
• Usa un requestId UUID v4, oppure un header Idempotency-Key identico, e mantieni la stessa azione, lo stesso ID e gli stessi argomenti nei tentativi successivi. La ripetizione di un risultato memorizzato nella cache non consuma un’altra chiamata mensile.
• Il prefisso di caricamento seleziona l’autorizzazione richiesta. tools utilizza transcription:write, subtitles utilizza subtitles:write, projects utilizza projects:write e voices utilizza voices:write.
• Per strumenti, sottotitoli e progetti, kind accetta transcription, video_to_srt, add_subtitles, animated_captions o project. Il kind selezionato determina i limiti del flusso di lavoro; il prefisso non impone un kind.
• Il kind scelto applica i propri limiti: transcription 200 MiB; video_to_srt e add_subtitles 300 MiB; animated_captions 250 MiB e solo audio; project usa il limite di caricamento del piano (Beginner 5 GiB, Starter 10 GiB, Creator 20 GiB, Pro 30 GiB, Scale 40 GiB, Enterprise 60 GiB). I contenuti multimediali autonomi durano al massimo 2 ore. I sottotitoli consentono 30 minuti su Beginner e 60 minuti sui piani pubblici superiori, più una tolleranza del contenitore di 2 secondi. La durata del progetto è al massimo di 2 ore, o 3 ore su Enterprise.
• Questa azione viene eseguita in modo asincrono. Interroga periodicamente action_request_get con il nome dell’operazione e il requestId originale fino al completamento, prima di prelevare fileKey dal risultato.
• Con kind project, url può essere un link a un video YouTube (youtube.com/watch, youtu.be o youtube.com/shorts). Il video viene scaricato come in un’importazione dall’app web, con il limite di risoluzione YouTube del piano, dopo aver verificato la durata rispetto al piano; le dirette vengono rifiutate. Qualsiasi altro url deve essere un URL HTTPS pubblico diretto a un file audio o video: reindirizzamenti, credenziali, frammenti, porte diverse da 443 e indirizzi DNS non pubblici vengono rifiutati. Gli altri kind non accettano link YouTube; usa le azioni YouTube dedicate.
• filename è facoltativo quando il percorso dell’URL termina con un nome di file multimediale supportato. Il nome del file salvato viene sanificato. Il server rileva la durata effettiva prima di restituire un fileKey.
• L’importazione prepara il contenuto multimediale e consuma una chiamata di integrazione mensile riuscita; la quota giornaliera di generazioni dello strumento viene consumata solo dalla generazione successiva.

​

Utilizzo

​

Errori

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