VanceAI Open API documentation

L'API expose le moteur de traitement de VanceAI via un ensemble réduit et stable de points de terminaison REST. Vous soumettez une tâche avec un fichier ou une URL, vous interrogez son état, puis vous téléchargez le résultat. Les outils image et vidéo relèvent de la même ressource /v1/jobs — le tool choisi détermine le type de média et l'opération.

Toutes les requêtes API sont envoyées à :

https://cloud-vanceai.vanceai.com/api/v1

Chaque réponse est application/json. Toutes les requêtes doivent être authentifiées avec une clé API — voir Authentification.

L'API est entièrement asynchrone et repose sur trois étapes :

POST /v1/jobs            → returns a job_id immediately (status: "queued")
GET  /v1/jobs/{id}       → poll until status is "succeeded" or "failed"
GET  /v1/jobs/{id}/result → fetch a fresh, never-expiring download link

Un POST ne bloque jamais pendant l'upload ou le traitement. Il valide votre requête, réserve la tâche et renvoie un job_id en quelques millisecondes. Un worker en arrière-plan gère ensuite l'upload, le traitement et le résultat — ainsi, même des vidéos de plusieurs gigaoctets fonctionnent sans atteindre les délais d'expiration HTTP.

• Authentification — obtenez et utilisez votre clé API.
• Démarrage rapide — votre première tâche en quelques minutes.
• Tâches et cycle de vie — la référence complète des points de terminaison.

Les clés ressemblent à ceci et commencent toujours par le préfixe sk_live_ :

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Créez et révoquez les clés depuis le tableau de bord de votre compte VanceAI. La clé complète n'est affichée qu'une seule fois, à la création — conservez-la en lieu sûr. En cas de perte, révoquez la clé et créez-en une nouvelle. Voir Gestion des clés API.

Envoyez votre clé dans l'en-tête Authorization sous forme de bearer token à chaque requête :

Authorization: Bearer sk_live_a1b2c3d4e5f6...

Par exemple, pour vérifier votre solde de crédits :

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

Une clé manquante, malformée ou révoquée renvoie 401 avec un code d'erreur stable :

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been disabled.",
    "type": "auth"
  }
}

Consultez Erreurs pour la liste complète des codes et leur gestion.

Envoyez l'image en multipart form data, avec le tool et sa config. Vous pouvez uploader un fichier directement (jusqu'à 200 Mo) ou fournir une image_url publique.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}' \
  -F output_format=jpg

Ou soumettez une URL avec un corps JSON :

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "tool": "upscale",
    "config": { "scale": 4, "face_enhance": true },
    "output_format": "jpg"
  }'

La réponse renvoie immédiatement un job_id et un statut queued :

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

Interrogez GET /v1/jobs/{job_id} jusqu'à ce que status passe à succeeded (ou failed). Pour les images, un polling toutes les ~2 secondes suffit largement.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c... \
  -H "Authorization: Bearer sk_live_..."

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

Le result_url de l'étape 2 est un lien signé qui finit par expirer. Pour un lien qui n'expire jamais, appelez le point de terminaison de résultat, qui re-signe à la demande :

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o upscaled.jpg

Chaque tâche passe par ces statuts :

Pendant processing, le champ phase précise l'étape : uploading → syncing → processing. Le progress numérique (0–100) n'a de sens qu'une fois phase à processing ; pendant l'upload/la sync, il reste à 0. Pour les grandes vidéos, la phase d'upload peut prendre plusieurs minutes — jugez « est-ce bloqué ? » d'après phase, pas progress.

Les vidéos sont uploadées directement vers le stockage en deux étapes : les octets ne transitent pas par l'API et les fichiers de plusieurs gigaoctets ne sont pas limités par la taille de requête. Appelez d'abord POST /v1/uploads pour obtenir une URL d'upload présignée à usage unique, puis faites un PUT du fichier dessus. Les images sautent cette étape — uploadez-les directement lors de la création de la tâche (voir ci-dessous). L'upload vidéo multipart direct n'est pas pris en charge ; source_url reste accepté en alternative.

Paramètres de la requête

Exemple

curl https://cloud-vanceai.vanceai.com/api/v1/uploads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "clip.mp4",
    "file_size": 734003200,
    "content_type": "video/mp4"
  }'

Réponse — 201 Created

{
  "upload_id": "upl_8f3b1c2a...",
  "put_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "expires_at": "2026-06-13T08:30:00Z",
  "max_bytes": 5261334937
}

put_url est une URL présignée valable 24 heures. Uploadez-y les octets bruts avec un seul PUT — sans en-tête d'authentification, juste le fichier :

curl -X PUT --upload-file clip.mp4 \
  -H "Content-Type: video/mp4" \
  "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=..."

Une fois le PUT réussi, créez la tâche en passant l'upload_id au lieu d'un fichier — voir Créer une tâche. Chaque upload_id est à usage unique.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_8f3b1c2a...",
    "tool": "video_upscale",
    "config": { "scale": 2, "codec": "h264" }
  }'

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "video_upscale",
  "media": "video",
  "credits_estimated": 0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

La manière de fournir le média dépend du type. Images : un upload de fichier direct (multipart) ou une URL publique. Vidéos : un upload_id issu de l'étape d'upload ci-dessus, ou une source_url publique. Le tool sélectionne le type de média et l'opération.

Paramètres de la requête

Idempotence

Passez un en-tête Idempotency-Key pour réessayer en toute sécurité une requête de création sans dupliquer la tâche. Voir Limites de débit et idempotence.

Exemple

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a-unique-string" \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}'

Réponse — 202 Accepted

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

La réponse revient avant tout débit de crédits (credits_charged vaut 0). credits_estimated est une estimation préalable ; le débit définitif apparaît une fois la tâche en processing. Voir Crédits et facturation.

Renvoie le statut actuel d'une tâche. Interrogez jusqu'à ce que la tâche atteigne un statut final.

Réponse — 200 (processing)

{
  "job_id": "job_3f2a9c...",
  "status": "processing",
  "phase": "uploading",
  "progress": 0,
  "tool": "video_upscale",
  "media": "video",
  "result_url": null,
  "result": null,
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": null
}

Réponse — 200 (succeeded)

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

La forme de result est { width, height, size } pour les images et { width, height, duration, size, codec } pour la vidéo. Le result_url est un lien signé qui expirera — pour un lien permanent, utilisez le point de terminaison de résultat ci-dessous.

Redirige (302) vers une URL de résultat fraîchement signée — re-signée à chaque appel, donc le lien n'expire jamais. Utilisez ceci à chaque fois que vous devez télécharger la sortie, plutôt que de mettre en cache result_url.

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o result.jpg

Annule une tâche encore queued ou processing. Surtout utile pour les longues tâches vidéo. Les crédits réservés sont intégralement remboursés.

{ "job_id": "job_3f2a9c...", "status": "canceled" }

Une tâche déjà succeeded, failed ou canceled renvoie 409 not_cancelable.

Supprime un enregistrement de tâche et son résultat associé — utile pour nettoyer les ressources traitées pour la confidentialité ou la conformité. Si la tâche est en cours, elle est d'abord annulée (et les crédits remboursés).

{ "job_id": "job_3f2a9c...", "deleted": true }

• Supprimer une tâche déjà supprimée renvoie toujours 200 { "deleted": true } (idempotent).
• Vous ne pouvez supprimer que les tâches de votre propre compte ; les autres renvoient 404 job_not_found.

Les outils image prennent un objet config. L'option face_enhance (booléen) est facultative sur la plupart des outils. Définissez output_format dans la requête pour choisir jpg / png / webp.

{ "scale": 4, "face_enhance": true }

Les outils vidéo sont traités de bout en bout (pas de mode aperçu en v1). Les options quality (high / medium / low) et codec (h264 / h265) s'appliquent uniquement à video_hdr et video_face_enhance. Pour video_upscale, l'encodage de sortie est déterminé par le moteur d'upscaling, donc quality / codec ne sont pas utilisés (les envoyer n'a aucun effet).

{ "scale": 2 }

Demander un outil qui n'existe pas — ou qui n'est pas encore disponible (les opérations vidéo translate, colorize et subtitle ne sont pas en v1) — renvoie 400 unsupported_tool.

Le flux des crédits sur la durée de vie d'une tâche :

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_..."

{ "balance": 999.8, "used": 234.2, "frozen": 12.5 }

Les montants de crédits sont décimaux (certaines opérations coûtent une fraction de crédit).

Chaque clé API a une limite de débit. La dépasser renvoie 429 rate_limited avec des en-têtes décrivant votre fenêtre actuelle :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718093460

Les réponses peuvent aussi inclure un en-tête Retry-After (secondes) — respectez-le avant de réessayer.

Comme une seule tâche vidéo peut durer plusieurs minutes, le débit de requêtes seul ne suffit pas. Il existe aussi un plafond sur le nombre de tâches que votre compte peut avoir en cours (queued ou processing) simultanément — généralement plus bas pour la vidéo que pour les images.

Soumettre au-delà du plafond renvoie 429 concurrency_limit_exceeded. Attendez que des tâches en cours se terminent, puis réessayez. Le décompte est agrégé par compte ; répartir le travail sur plusieurs clés ne le contourne pas.

La v1 n'a pas de webhooks, vous interrogez donc GET /v1/jobs/{id}. Pour éviter de surcharger l'API :

• Intervalle suggéré : environ 2 s pour les images, 5 à 10 s pour la vidéo.
• Respectez l'en-tête Retry-After lorsqu'il est présent — c'est une indication pour le prochain polling.
• Arrêtez le polling une fois que la tâche atteint un statut final (succeeded / failed / canceled).

Des coupures réseau peuvent vous laisser incertain quant au succès d'un POST /v1/jobs. Pour réessayer en toute sécurité, envoyez un en-tête Idempotency-Key unique :

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f3b1c2a-...-unique" \
  -F [email protected] \
  -F tool=upscale

• Rejouer la même clé renvoie la tâche d'origine — pas de doublon, pas de double facturation.
• Générez une nouvelle clé par requête logique (un UUID convient bien).
• Réutiliser une clé avec un tool ou une config différents renvoie 409 idempotency_conflict.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for this operation.",
    "type": "billing"
  }
}

code est une chaîne stable — branchez-vous dessus. message est lisible et peut changer. type est la grande catégorie : auth, billing, validation, processing, rate_limit ou server.

Quand une requête est rejetée d'emblée, vous obtenez le statut HTTP correspondant et un corps error :

Quand une tâche échoue *de façon asynchrone*, interroger GET /v1/jobs/{id} renvoie HTTP 200 avec status: "failed" et un code dans error.code. N'attendez pas de 5xx pour une tâche échouée — la requête elle-même a réussi.

Dans votre tableau de bord, créez une nouvelle clé et donnez-lui un nom reconnaissable (par exemple my-app-prod). Le secret complet — commençant par sk_live_ — n'est affiché qu'une seule fois, juste après la création.

Le tableau de bord liste vos clés par nom, statut, un court préfixe (p. ex. sk_live_a1b2) pour l'identification, et la date de dernière utilisation de chaque clé. Le secret complet n'est plus jamais affiché — seulement le préfixe.

La désactivation d'une clé prend effet immédiatement — toute requête ultérieure avec celle-ci renvoie 401 invalid_api_key.

• La révocation est permanente. Pas de réactivation ; créez plutôt une nouvelle clé.
• Vous ne pouvez gérer que les clés appartenant à votre propre compte.

Plusieurs clés actives peuvent coexister, ce qui rend la rotation transparente : créez une nouvelle clé, basculez votre application dessus, confirmez que le trafic a migré, puis révoquez l'ancienne clé. Utiliser une clé distincte par application ou environnement limite l'impact en cas de fuite.

La première version stable inclut :

• API de tâches unifiée pour image et vidéo — POST /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/result, POST /v1/jobs/{id}/cancel, DELETE /v1/jobs/{id} et GET /v1/credits.
• 8 outils image et 1 outil vidéo (agrandissement).
• Fichiers volumineux : uploads directs d'images jusqu'à 200 Mo ; vidéos via upload direct en deux étapes ; tout média via source_url (protégé contre le SSRF).
• Traitement asynchrone avec une vérification préalable des crédits et un worker en arrière-plan.
• Réservations de crédits avec remboursement intégral en cas d'échec ou d'annulation.
• Codes d'erreur stables, prise en charge de Idempotency-Key, limites de débit par clé et limites de concurrence par compte.
• Upload vidéo direct en deux étapes — POST /v1/uploads émet une URL présignée pour uploader les vidéos directement vers le stockage (un seul PUT jusqu'à ~4,9 Go), en contournant la limite de taille de requête.
• Facturation vidéo exacte — le serveur mesure la résolution, la durée et la fréquence d'images avec ffprobe, et vérifie au préalable la résolution de sortie par rapport à la limite du moteur.