alpha

Appeler des points de terminaison HTTP

🤖/http/request appelle votre application pendant une Assembly et émet les fichiers d’entrée sélectionnés ou télécharge les URL de fichiers de résultat renvoyées.

Appelle un point de terminaison HTTP pendant l’Assembly et attend un JSON facultatif décrivant zéro ou plusieurs fichiers d’entrée ou URL de fichiers de résultat à émettre depuis ce Step.

Votre point de terminaison doit renvoyer une réponse 2xx. Un corps vide, [] ou { "files": [] } signifie que ce Step n’émet aucun fichier. Vous pouvez aussi renvoyer un objet fichier, un tableau d’objets fichier, ou { "files": [...] } / { "files": { "name": {...} } }. Les objets fichier renvoyés doivent inclure soit un champ path correspondant à l’un des chemins de fichiers d’entrée envoyés à votre point de terminaison, soit un champ url contenant une URL HTTP(S) que Transloadit télécharge et émet comme nouveau fichier de résultat.

Exemple d’utilisation

Demander à votre application quels fichiers d’entrée doivent poursuivre le traitement :

{
  "steps": {
    "request": {
      "method": "POST",
      "payload": "metadata",
      "robot": "/http/request",
      "url": "https://example.com/transloadit/files",
      "use": ":original"
    }
  }
}

Paramètres

interpolate
boolean | Record<string, boolean>
Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.

Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur false pour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel sur false pour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre sur true ou définissez le chemin de ce champ sur true pour réactiver l’interpolation.

Utilisez des noms de champs tels que path, ou des chemins avec points tels que ffmpeg.vf pour les objets imbriqués.
output_meta
Record<string, boolean> | boolean | Array<string>
Permet de spécifier un ensemble de métadonnées dont le calcul est plus coûteux en puissance CPU et qui sont donc désactivées par défaut afin que le traitement de vos Assemblies reste rapide.

Pour les images, vous pouvez ajouter "has_transparency": true dans cet objet pour déterminer si l’image contient des parties transparentes, et "dominant_colors": true pour extraire de l’image un tableau de codes couleur hexadécimaux.

Pour les images, vous pouvez également ajouter "blurhash": true pour extraire une chaîne BlurHash — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.

Pour les images, "thumbhash": true extrait plutôt un ThumbHash encodé en base64 dans meta.thumbhash, accompagné de meta.has_alpha (qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un décodage échoué ou limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.

Définissez cette option sur le Step qui produit l’image, par exemple /upload/handle pour les originaux téléversés ou /image/resize pour les sorties traitées. La définir uniquement sur /transloadit/store ne déclenche pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.

Pour les vidéos, vous pouvez ajouter le paramètre "colorspace": true pour extraire l’espace colorimétrique de la vidéo de sortie.

Pour les vidéos, vous pouvez également ajouter "interlaced": true pour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteux field_order avec une passe d’échantillonnage idet limitée sur les premières images de la source, et expose interlaced, field_order ainsi qu’un objet de diagnostic interlace_detection sous file.meta. Cette opération est coûteuse en calcul et facturée en conséquence.

Pour l’audio, vous pouvez ajouter "mean_volume": true pour obtenir une valeur unique représentant le volume moyen du fichier audio.

Vous pouvez également définir cette option sur false pour ignorer l’extraction des métadonnées et accélérer le transcodage.
user_meta
Record<string, any>(par défaut : {})
Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.

L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur user_meta existante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.

Dans les Steps de traitement, ${file.*} désigne la première entrée et ${result.*} le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur :original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.

Les Steps en aval lisent ${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.
result
boolean(par défaut : false)
Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON
queue
batch
Définir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file
force_accept
boolean(par défaut : false)
Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.

Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.
ignore_errors
boolean | Array<meta | execute>(par défaut : [])
Ignore les erreurs pendant certaines phases du traitement.

Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

Définir cette valeur sur true équivaut à ["meta", "execute"] : les erreurs seront alors ignorées dans les deux phases.
use
string | Array<string> | Array<object> | object
Indique quel(s) Step(s) utiliser comme entrée.
- Vous pouvez choisir n’importe quel nom pour les Steps, sauf ":original" (réservé aux téléversements des utilisateurs gérés par Transloadit)
- Vous pouvez fournir plusieurs Steps en entrée à l’aide de tableaux :
```
{
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
```
- Vous pouvez également étiqueter les Steps d’entrée avec as pour transmettre une intention sémantique aux Robots :
```
{
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}
```
Astuce

C’est probablement tout ce que vous devez savoir sur use, mais vous pouvez consulter les cas d’utilisation avancés.
url — obligatoire
string
Le point de terminaison HTTP ou HTTPS à appeler.
method
DELETE | GET | PATCH | POST | PUT(par défaut : "POST")
Méthode HTTP à utiliser pour la requête.
payload
none | metadata | file | files(par défaut : "none")
Contrôle ce qui est envoyé à votre point de terminaison.
- none : n’envoie aucun corps de requête.
- metadata : envoie un corps JSON contenant les métadonnées de l’Assembly, les champs, le Step précédent et les métadonnées des fichiers.
- file : envoie des données de formulaire multipart avec un champ JSON payload et le premier fichier d’entrée sous forme de partie file.
- files : envoie des données de formulaire multipart avec un champ JSON payload et tous les fichiers d’entrée sous forme de parties files[] répétées. Pour envoyer plusieurs fichiers d’entrée en une seule requête, définissez bundle_steps: true dans les options use avancées.
L’objet JSON payload contient assembly, fields, previous_step, file et files. file contient les métadonnées du premier fichier d’entrée ou vaut null ; files est un tableau de métadonnées des fichiers d’entrée.
headers
Array<string> | Array<Record<string, boolean | string | number | string | null>> | Record<string, boolean | string | number | string | null> | string(par défaut : [])
En-têtes de requête personnalisés.

Les en-têtes peuvent être spécifiés sous forme de tableau de chaînes au format "Header-Name: value", de tableau d’objets, d’objet de correspondance ou de chaîne JSON qui sera analysée en objet/tableau.

Les noms d’en-têtes doivent être des jetons HTTP valides. Les valeurs d’en-têtes peuvent contenir des tabulations horizontales, mais les autres caractères de contrôle, y compris les retours chariot et les sauts de ligne, sont rejetés.

Dans un tableau de chaînes d’en-têtes, "Header-Name;" envoie une valeur d’en-tête vide. Chaque entrée doit être un en-tête littéral ; la lecture d’en-têtes depuis un fichier avec @filename n’est pas prise en charge.
timeout
string | number(par défaut : 60)
Nombre maximal de secondes d’attente pour la requête HTTP.

Le délai d’expiration effectif est la plus petite valeur entre celle-ci et le plafond côté serveur de Transloadit. Ce plafond est de 30 secondes plus 1 seconde par MiB envoyé à votre point de terminaison.
max_response_size
string | number(par défaut : 1048576)
Taille maximale de réponse acceptée, en octets. La réponse devrait normalement être un petit document JSON.
max_result_files
string | number(par défaut : 10)
Nombre maximal de fichiers que le point de terminaison peut renvoyer.
max_result_file_size
string | number(par défaut : 104857600)
Taille maximale autorisée, en octets, pour chaque fichier de résultat renvoyé par URL. Si le serveur distant indique une taille de fichier supérieure, le téléchargement du résultat est refusé avant de commencer. Si le serveur distant n’indique pas de taille à l’avance, le téléchargement est interrompu dès que cette limite est dépassée.
result_download_timeout
string | number(par défaut : 120)
Nombre maximal de secondes consacrées au téléchargement de chaque fichier de résultat renvoyé par URL.

Appeler des points de terminaison HTTP

Exemple d’utilisation

Paramètres

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`url` — obligatoire

`method`

`payload`

`headers`

`timeout`

`max_response_size`

`max_result_files`

`max_result_file_size`

`result_download_timeout`

Appeler des points de terminaison HTTP

Exemple d’utilisation

Paramètres

interpolate

output_meta

user_meta

result

queue

force_accept

ignore_errors

use

url — obligatoire

method

payload

headers

timeout

max_response_size

max_result_files

max_result_file_size

result_download_timeout

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`url` — obligatoire

`method`

`payload`

`headers`

`timeout`

`max_response_size`

`max_result_files`

`max_result_file_size`

`result_download_timeout`