> ## 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. # Finaliser un envoi de média (projets) > Finalisez les parties envoyées et recevez le fileKey qui vous appartient, à utiliser dans les actions de génération. Finalisez les parties envoyées et recevez le fileKey qui vous appartient, à utiliser dans les actions de génération. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/projects_upload_complete ``` ## Authentification et autorisations Envoyez une clé API VoiceCheap dans cet en-tête. Authorization: Bearer avec la même clé API est également accepté. Les jetons d’accès OAuth sont acceptés uniquement par MCP, pas par cet endpoint REST. Autorisations requises: `projects:write`. Un abonnement payant actif est requis. Les autorisations ne modifient ni les rôles dans l’équipe, ni la propriété des ressources, ni les crédits média, ni les limites du forfait. ## Paramètres Valeur textuelle. Format: "uuid". Motif: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$`. Liste de valeurs. Consultez le schéma d’entrée complet pour connaître la structure de ses éléments. Nombre minimal d’éléments: 1. Nombre maximal d’éléments: 10000. Facultatif au niveau du transport : le serveur injecte un identifiant avant la validation si ce champ est omis. Fournissez votre propre UUID v4 stable pour récupérer le résultat en toute sécurité si la réponse est perdue. Format: "uuid". Motif: `^[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}$`. Le JSON Schema ci-dessous conserve les noms de champs exacts, les types imbriqués, les valeurs par défaut, les limites et les valeurs acceptées exposés par la découverte. Les règles supplémentaires entre champs figurent dans les notes de l’opération. ```json theme={null} { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parts": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\r\\n]+$" } }, "required": ["partNumber", "etag"], "additionalProperties": false } }, "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": ["uploadId", "parts"], "additionalProperties": false } ``` ## Idempotence Utilisez un UUID v4 dans requestId ou dans l’en-tête HTTP Idempotency-Key pour chaque mutation. Après une erreur réseau, réutilisez le même identifiant avec des arguments identiques. Si les deux sont fournis, ils doivent correspondre. Rejouer une requête enregistrée ne répète pas l’opération et ne décompte pas un nouvel appel mensuel. Les requêtes en échec ou interrompues ne sont pas relancées automatiquement. Toute mutation peut renvoyer HTTP 202 lorsqu’une nouvelle tentative retrouve la même requête encore en cours, même si sa première exécution est habituellement synchrone. Si l’exécution est terminée mais que resultStored vaut false, une nouvelle tentative renvoie HTTP 200 avec l’état de la requête enregistrée, au lieu du résultat d’origine. Récupérez le résultat avec l’action d’historique, de résultat ou de téléchargement de son domaine. ## Exemples de requêtes Remplacez les exemples d’identifiants de ressources et de clés média par des valeurs renvoyées pour votre compte. Conservez le même identifiant de requête lorsque vous réessayez la même mutation. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_upload_complete' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"uploadId":"a1b2c3d4-e5f6-4789-8abc-def012345678","parts":[{"partNumber":1,"etag":"0123456789abcdef0123456789abcdef"}],"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}' ``` ```javascript JavaScript theme={null} const input = { uploadId: 'a1b2c3d4-e5f6-4789-8abc-def012345678', parts: [ { partNumber: 1, etag: '0123456789abcdef0123456789abcdef', }, ], requestId: '13579bdf-2468-4ace-8bdf-0123456789ab', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_upload_complete', { 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/projects_upload_complete", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"uploadId": "a1b2c3d4-e5f6-4789-8abc-def012345678", "parts": [{"partNumber": 1, "etag": "0123456789abcdef0123456789abcdef"}], "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) ``` ## Réponse Une première exécution réussie renvoie HTTP 200 avec le résultat de l’opération sous data. Une nouvelle tentative peut renvoyer à la place l’état de la requête enregistrée. L’exemple présente une réponse possible, sans tous les champs facultatifs. Le fileKey finalisé appartenant à l’acteur et l’URL de lecture du média. Transmettez fileKey à l’action de génération ou de voix suivante. ```json HTTP 200 theme={null} { "data": { "fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4", "readUrl": "https://media.example.com/uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4" }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "projects_upload_complete", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "projects_upload_complete", "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" } ``` ## Champs du résultat | Champ | Description | | - | - | | `data.fileKey` | Référence d’un envoi finalisé appartenant à l’utilisateur, utilisée par les actions de génération et de voix. | | `data.readUrl` | URL de lecture renvoyée pour le fichier source finalisé. Traitez-la comme une donnée privée d’accès au média. | ## Récupérer et suivre cette requête Utilisez le même identifiant, même après une perte de connexion. Si resultStored vaut false, récupérez le résultat avec l’action d’historique, de résultat ou de téléchargement correspondante. Ne lancez jamais une seconde génération uniquement pour vérifier l’avancement. ```bash theme={null} 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_complete"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "projects_upload_complete", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4", "readUrl": "https://media.example.com/uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4" } } } ``` ## Notes de l’opération * Nécessite un abonnement payant et l’autorisation de l’action. L’offre personnelle d’outils de l’acteur est vérifiée de nouveau à l’exécution ; les outils enregistrés et les références d’envoi appartiennent à cet acteur, y compris lorsque l’identifiant d’accès est associé à une équipe. * Une action réussie consomme un appel mensuel API/MCP partagé. Beginner autorise 500 appels/mois, Starter 5,000 et Creator 25,000 ; Pro, Scale et Enterprise n’ont pas de plafond mensuel. Les limites par minute restent applicables : respectivement 30, 60, 120, 180, 300 et 600. Les quotas de génération des outils sont distincts. * Utilisez un requestId au format UUID v4, ou un en-tête Idempotency-Key identique, et conservez la même action, le même identifiant et les mêmes arguments lors des nouvelles tentatives. La restitution d’un résultat en cache ne consomme pas d’appel mensuel supplémentaire. * Le préfixe d’envoi détermine l’autorisation requise. tools utilise transcription:write, subtitles utilise subtitles:write, projects utilise projects:write et voices utilise voices:write. * Pour les outils, les sous-titres et les projets, kind accepte transcription, video\_to\_srt, add\_subtitles, animated\_captions ou project. Le champ kind sélectionné détermine les limites du workflow ; le préfixe n’impose pas de kind. * Le champ kind choisi applique ses propres limites : transcription 200 MiB ; video\_to\_srt et add\_subtitles 300 MiB ; animated\_captions 250 MiB et audio uniquement ; project utilise la limite d’envoi de l’offre (Beginner 5 GiB, Starter 10 GiB, Creator 20 GiB, Pro 30 GiB, Scale 40 GiB, Enterprise 60 GiB). Les médias utilisés seuls sont limités à 2 heures. Les sous-titres autorisent 30 minutes avec Beginner et 60 minutes avec les offres publiques supérieures, plus une tolérance de 2 secondes pour le conteneur. La durée d’un projet est limitée à 2 heures, ou 3 heures avec Enterprise. * Soumettez chaque partie envoyée exactement une fois avec l’ETag renvoyé par son PUT. Les parties sont triées par partNumber avant la finalisation ; les ETags peuvent être entourés de guillemets ou non. * Une finalisation réussie supprime la session active. Réutilisez le même requestId pour récupérer son résultat après la perte d’une réponse ; ne soumettez pas de nouvelle finalisation pour la session consommée. * Finaliser un envoi ne consomme pas de quota quotidien de génération. La génération, effectuée séparément, détermine la consommation média. ## Utilisation Chaque invocation réussie consomme un appel du quota mensuel API/MCP. Les crédits média et les quotas de génération propres à l’opération s’appliquent également. ## Erreurs | Statut HTTP | Code | Signification ou solution | | - | - | - | | 400 | `BAD_REQUEST` | Des parties sont manquantes, dupliquées ou hors limites ; fournissez chaque partie exactement une fois. | | 400 | `CREDENTIAL_IN_QUERY` | Des identifiants ont été fournis dans un paramètre de requête access\_token ou api\_key. Envoyez les identifiants dans les en-têtes. | | 400 | `IDEMPOTENCY_CONFLICT` | Les ID de requête de l’en-tête et du corps diffèrent. | | 400 | `INVALID_REQUEST_ID` | requestId ou Idempotency-Key n’est pas un UUID v4. | | 400 | `VALIDATION_ERROR` | Les arguments ne respectent pas le schéma de l’action, ou un argument inconnu a été fourni. | | 401 | `API_KEY_EXPIRED` | La clé API a expiré. | | 401 | `INVALID_API_KEY` | Fournissez une clé API valide et non expirée. | | 401 | `INVALID_CREDENTIAL` | L’en-tête Authorization est mal formé ou entre en conflit avec x-api-key. | | 401 | `MISSING_CREDENTIAL` | Aucun identifiant d’authentification utilisable n’a été fourni dans les en-têtes, ou il dépassait 4096 caractères. | | 401 | `UNAUTHORIZED` | La session d’envoi appartient à un autre acteur authentifié. | | 401 | `USER_NOT_FOUND` | Le compte associé à l’identifiant d’accès n’existe plus. | | 403 | `ACCOUNT_UNAVAILABLE` | Le compte à l’origine de l’action ou le compte de facturation est indisponible ou en cours de suppression. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | L’utilisateur associé aux identifiants d’authentification appartient à plusieurs équipes, ce qui rend le contexte de facturation ambigu. | | 403 | `INSUFFICIENT_SCOPE` | La clé API ou la connexion MCP ne dispose pas de l’autorisation requise pour cette action. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Les limites d’intégration du compte n’ont pas pu être vérifiées. | | 403 | `PAID_SUBSCRIPTION_REQUIRED` | L’acteur authentifié ne dispose plus d’un abonnement payant au moment de l’exécution de cette action d’outil. | | 403 | `SUBSCRIPTION_REQUIRED` | Utilisez un abonnement payant actif. | | 403 | `TEAM_OWNER_NOT_FOUND` | Le compte du propriétaire effectif de l’équipe est introuvable. | | 404 | `NOT_FOUND` | La session d’envoi est absente, expirée, finalisée ou annulée. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Ce compte a déjà 10 actions d’intégration en cours. Suivez une requête existante avant d’en démarrer une autre. | | 409 | `IDEMPOTENCY_CONFLICT` | Réutilisez un identifiant uniquement avec la même opération et les mêmes arguments. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Les appels utilisés et en attente ont atteint le quota mensuel partagé API/MCP. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Le compte a atteint sa limite d’intégration par minute ; consultez retryAfterSeconds. | | 500 | `INTERNAL_ERROR` | Vérifiez l’état de la requête enregistrée et l’historique de la ressource avant de décider de réessayer une mutation. | | 503 | `ACTION_RESULT_UNAVAILABLE` | L’action a été exécutée, mais l’enregistrement du résultat de la requête n’a pas pu être confirmé. Interrogez la même action avec le même requestId et examinez l’historique de la ressource avant de lancer une autre écriture. | | 503 | `INTERNAL_ERROR` | Le service de sessions d’envoi est indisponible. Vérifiez la requête d’origine avant de réessayer une écriture. | | 503 | `SERVER_RESTARTING` | Le serveur redémarre. Réessayez dans un instant en conservant le même identifiant de requête pour une mutation. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["projects:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.