Référence de l’API — points de terminaison et objets

Référence de l’API

Référence de l’API REST : envoyer, interroger et annuler des générations, lister les modèles et les prix, obtenir des devis, consulter votre solde et importer des images, vidéos et fichiers audio — avec exemples.

L’API s’articule autour de quelques ressources : generations (les tâches que vous lancez), modèles (les modèles disponibles et leur prix), quotes, votre account et vos uploads. Toutes les requêtes et réponses sont au format JSON sur HTTPS.

URL de basehttps://cheapergen.com/api/v1

Authentifiez-vous avec Authorization: Bearer cg_live_… (voir Authentification). Les erreurs suivent le format décrit dans Erreurs. Tous les points de terminaison envoient des en-têtes CORS ; toutefois, n’exposez jamais votre clé dans un navigateur : seuls les points de terminaison publics sont destinés à être appelés côté client.

Points de terminaison de l’API
Point de terminaison	Description
POST/run/{endpoint}	Envoyer une génération
GET/generations/{id}	Récupérer une génération
GET/generations	Lister les générations
POST/generations/{id}/cancel	Annuler une génération en attente
DELETE/generations/{id}	Supprimer une génération et ses médias
GET/models	Lister les modèles et leurs tarifs
GET/models/{vendor}/{model}	Récupérer un modèle et ses schémas d’entrée
POST/quote/{endpoint}	Estimer le prix d’une entrée
GET/account	Solde, crédit image et recharge automatique
GET/account/pricing	Votre forfait et vos tarifs personnalisés
POST/uploads	Téléverser un fichier image, vidéo ou audio en entrée
GET/webhooks/secret	Votre secret de signature des webhooks

Envoyer une génération#

POST/api/v1/run/{endpoint}Clé API requise

Lance une génération asynchrone et renvoie 202 Accepted avec un objet de génération à l’état queued. Le prix est alors réservé sur votre solde (voir Facturation).

Paramètres de chemin

endpointstringrequis: L’identifiant du point de terminaison du modèle, {vendor}/{model}/{task} — par exemple bytedance/seedance-2.0-fast/text-to-video. Tous les identifiants figurent sur la page Modèles.

Corps

…model inputsobjectrequis: Champs d’entrée du point de terminaison, tels que prompt, resolution ou image_url. Les champs, types, valeurs par défaut et valeurs autorisées de chaque modèle sont documentés sur sa page API et renvoyés sous forme de schéma JSON par Récupérer un modèle. Les champs inconnus sont rejetés.
webhook_urlstring (https URL): Facultatif. Nous envoyons une requête POST à cette URL lorsque la génération est terminée. Voir Webhooks.
retentionstring: Facultatif. Durée de conservation du prompt, des entrées et des résultats de cette génération : immediate, 1h, 1d, 7d ou 30d. La valeur par défaut est celle de votre compte (1d). Tous les comptes peuvent réduire cette durée ; 7d et 30d nécessitent un paramètre de conservation réservé aux entreprises. Voir Conservation des données.
allow_fallback_priceboolean: Optionnel, par défaut true. Si la capacité habituelle pour cette requête n’est pas disponible, elle peut être traitée sur une capacité plus coûteuse au tarif tarif d’urgence — au maximum au tarif officiel du modèle et sans jamais dépasser max_cost_usd. Cela s’applique à l’envoi de la requête (le prix figure dans la réponse et dans /quote) et, si la capacité tombe en panne après l’acceptation de la tâche, à un transfert ultérieur (le supplément est alors réservé ; pricing.fallback et les webhooks le signalent). Définissez false pour ne jamais payer plus que le prix annoncé. Avec une formule Pro ou Max, une tâche acceptée peut sinon aussi passer à un prix supérieur, au plus le tarif standard : vous obtenez 503 fallback_price_declined plutôt qu’un tarif plus élevé, ou la tâche échoue et est remboursée.
max_cost_usdnumber: Facultatif. Le montant maximal que vous acceptez de payer pour cette génération, prix d’urgence compris. Au-delà, vous recevez 400 max_cost_exceeded et rien ne vous est facturé ; la tâche ne basculera jamais ensuite vers un tarif supérieur.

const resp = await fetch("https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }),
});
const generation = await resp.json();

import os, requests

resp = requests.post(
    "https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video",
    headers={"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"},
    json={
        "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5
    },
)
generation = resp.json()

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Réponse · 202 Accepted

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

Erreurs : 400 invalid_request (validation), 401 unauthorized, 402 insufficient_balance, 404 not_found (point de terminaison inconnu), 429 rate_limited (débit des requêtes, ou votre file de générations en attente est pleine), 503 model_unavailable, 503 pricing_unavailable (réessayez dans quelques secondes ; rien n’a été facturé), 503 fallback_price_declined (seul le tarif d’urgence est disponible et vous avez envoyé allow_fallback_price: false), 400 max_cost_exceeded.

Récupérer une génération#

GET/api/v1/generations/{id}Clé API requise

Renvoie une génération par ID. Si une vérification de l’état est nécessaire, elle est effectuée avant la réponse : il suffit donc d’interroger ce point de terminaison pour suivre une tâche jusqu’à son terme. Renvoie 404 not_found si l’ID est inconnu ou si la génération appartient à un autre compte.

Requête

curl https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "succeeded",
  "input": {
    "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": "2026-10-15T09:21:09.031Z",
  "completed_at": "2026-10-15T09:22:31.870Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:22:31.870Z",
  "purged_at": null
}

Lister les générations#

GET/api/v1/generationsClé API requise

Liste vos générations, de la plus récente à la plus ancienne. Inclut les tâches envoyées depuis Studio et les espaces de test.

Paramètres de requête

limitinteger: Nombre de résultats par page, de 1 à 100. Valeur par défaut : 20.
cursorstring: Le next_cursor de la page précédente.
statusstring: Ne renvoie que les générations ayant l’un de ces états : queued, running, succeeded, failed ou canceled.
modelstring: Ne renvoie que les générations associées à cet identifiant de modèle, par exemple bytedance/seedance-2.0-fast.
sourcestring: Ne renvoie que les générations créées depuis playground (Studio et pages de modèles), api ou mcp (agents IA).

Requête

curl "https://cheapergen.com/api/v1/generations?limit=2&status=succeeded" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gen_8c2QmX1nq0k4Lw7Z",
      "object": "generation",
      "model": "bytedance/seedance-2.0-fast",
      "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
      "mode": "text-to-video",
      "status": "succeeded",
      "input": {
        "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio": true
      },
      "output": {
        "video": {
          "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
          "content_type": "video/mp4"
        }
      },
      "error": null,
      "cost": {
        "amount_usd": 0.4494,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    },
    {
      "id": "gen_3vYk2PqL9sTn0bWd",
      "object": "generation",
      "model": "bytedance/seedream-5.0-pro",
      "endpoint": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "status": "succeeded",
      "input": {
        "prompt": "Photo éditoriale d’une machine à espresso noire mate sur du travertin, lumière douce de fenêtre, 85 mm",
        "aspect_ratio": "1:1",
        "size": "2K"
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
            "content_type": "image/png"
          }
        ]
      },
      "error": null,
      "cost": {
        "amount_usd": 0.0665,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    }
  ],
  "next_cursor": "gen_3vYk2PqL9sTn0bWd"
}

La valeur de next_cursor est null sur la dernière page.

Annuler une génération#

POST/api/v1/generations/{id}/cancelClé API requise

Annule une génération encore à l’état queued et rembourse intégralement le montant réservé. Renvoie la génération mise à jour avec status: "canceled". Renvoie 409 conflict si la génération est déjà en cours d’exécution ou terminée, ou si le modèle ne permet pas d’annuler les tâches en attente.

Requête

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "canceled",
  "input": {
    "prompt": "Travelling avant lent sur un céramiste qui façonne un vase à l’heure dorée, poussière dans la lumière, faible profondeur de champ",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": "2026-10-15T09:21:06.200Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:21:06.200Z",
  "purged_at": null
}

Supprimer une génération#

DELETE/api/v1/generations/{id}Clé API requise

Supprime une génération : ses fichiers de résultat, les entrées importées qu’aucune autre génération n’utilise, le prompt et l’entrée sont supprimés immédiatement ; elle n’apparaît plus dans les listes et GET renvoie 404. Les données de facturation (débit du registre et totaux d’utilisation) sont conservées. Une génération encore queued est d’abord annulée et son montant réservé remboursé en totalité ; si elle ne peut plus être annulée (elle est en cours, ou son modèle ne permet pas d’annuler les tâches en attente), renvoie 409 conflict : attendez qu’elle se termine.

Requête

curl -X DELETE https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "deleted": true
}

L’objet de génération#

idstring: Identifiant unique préfixé par gen_.
objectstring: Toujours "generation".
modelstring: Identifiant du modèle, par exemple bytedance/seedance-2.0-fast.
endpointstring: Identifiant du point de terminaison auquel la tâche a été envoyée, par exemple bytedance/seedance-2.0-fast/text-to-video.
modestring: Tâche : text-to-video, image-to-video, reference-to-video, text-to-image ou image-edit.
statusstring: queued → running → succeeded | failed ou canceled. Voir Générations.
inputobject: The validated input, with defaults filled in.
outputobject | null: Défini en cas de réussite. Vidéo : { "video": { "url", "content_type" } }. Image : { "images": [{ "url", "content_type" }] }. Une image remplacée par le filtre de sécurité (elle apparaît vide) possède aussi "safety_filtered": true ; elle est facturée comme n’importe quel autre résultat.
errorobject | null: Défini en cas d’échec : { "code", "message", "reason", "hint", "retryable", "refunded" }, ainsi que param (champ à modifier) et detail (formulation du fournisseur) si ces informations sont connues. reason indique la raison — par exemple content_blocked, invalid_input, upstream_unavailable. Voir motifs d’échec.
costobject: amount_usd, currency ("usd") et estimated — true tant que le montant est réservé, puis false une fois le montant finalisé. Les générations échouées ou annulées ne coûtent 0.
pricingobject: custom_price (votre tarif personnalisé : tarif contractuel ou tarif de votre forfait Pro ou Max), volume_level (1 = Pro, 2 = Max lorsque le forfait a fixé le tarif, sinon null), standard_usd (le coût habituel de cette requête pour vous) et fallback : null, ou { "active", "reason", "message", "standard_usd", "amount_usd" } si le tarif d’urgence a été appliqué — au maximum le prix officiel, défini par allow_fallback_price et plafonné à max_cost_usd.
sourcestring: "api" ou "playground" (Studio et pages de modèles).
created_atstring: ISO 8601 timestamp of submission.
started_atstring | null: When the model started generating.
completed_atstring | null: When the generation reached a final state.
retentionstring | null: Générations API : immediate, 1h, 1d, 7d ou 30d. null pour les générations Studio, conservées jusqu’à leur suppression.
expires_atstring | null: Temps de conservation du contenu (prompt, entrées, résultats et médias), défini à la fin de la génération. Avec immediate, le délai passe à 10 minutes après la première livraison du résultat.
purged_atstring | null: À renseigner une fois le contenu supprimé. output vaut alors null, input ne conserve que les paramètres qui déterminent le prix et content_expired en indique la raison. Le coût et les horodatages sont conservés.
urlsobject: Uniquement dans la réponse à l’envoi : les URL get et cancel de cette génération.

Lister les modèles#

GET/api/v1/modelsPublic · sans authentification

Renvoie tous les modèles disponibles, leurs points de terminaison et leurs tarifs en direct. Les tarifs sont par unit (second de vidéo ou image) ; list_price_usd est le tarif public de référence et discount_pct l’économie en pourcentage.list_price_source indique le type de tarif : official (tarif public du développeur) ou reference (un autre tarif, nommé par list_price_label — par exemple fal API pour un modèle dont le développeur ne commercialise pas d’API internationale).

Requête

curl https://cheapergen.com/api/v1/models

Réponse · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "object": "model",
      "name": "Seedance 2.0 Fast",
      "vendor": "ByteDance",
      "category": "video",
      "available": true,
      "url": "https://cheapergen.com/models/bytedance/seedance-2.0-fast",
      "endpoints": [
        {
          "id": "bytedance/seedance-2.0-fast/text-to-video",
          "mode": "text-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/image-to-video",
          "mode": "image-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/reference-to-video",
          "mode": "reference-to-video",
          "output": "video"
        }
      ],
      "pricing": {
        "unit": "second",
        "list_price_source": "official",
        "list_price_label": "Official",
        "tiers": [
          {
            "tier": "480p",
            "price_usd": 0.050086,
            "list_price_usd": 0.056246,
            "discount_pct": 11
          },
          {
            "tier": "720p",
            "price_usd": 0.08988,
            "list_price_usd": 0.12096,
            "discount_pct": 26
          }
        ]
      },
      "deprecation": null,
      "upcoming_price_changes": []
    }
  ]
}

Limité à un seul modèle pour alléger l’exemple.

Récupérer un modèle#

GET/api/v1/models/{vendor}/{model}Public · sans authentification

Renvoie un modèle avec un schéma JSON pour les entrées de chacun de ses points de terminaison — utile pour créer des formulaires ou valider des requêtes avant envoi. Renvoie 404 not_found si le modèle est inconnu.

Requête

curl https://cheapergen.com/api/v1/models/bytedance/seedream-5.0-pro

Réponse · 200 OK

{
  "id": "bytedance/seedream-5.0-pro",
  "object": "model",
  "name": "Seedream 5.0 Pro",
  "vendor": "ByteDance",
  "category": "image",
  "available": true,
  "description": "Seedream 5.0 Pro de ByteDance crée et retouche des images photoréalistes jusqu’en 2K, avec des retouches précises de plusieurs images et un rendu fidèle du texte.",
  "url": "https://cheapergen.com/models/bytedance/seedream-5.0-pro",
  "endpoints": [
    {
      "id": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "label": "Texte en image",
      "output": "image",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "title": "Prompt",
            "description": "Décrivez le plan : sujet, action, mouvement de caméra, éclairage et style.",
            "type": "string",
            "maxLength": 5000
          },
          "aspect_ratio": {
            "title": "Format d’image",
            "description": "Format de l’image de sortie.",
            "type": "string",
            "enum": [
              "1:1",
              "4:3",
              "3:4",
              "16:9",
              "9:16",
              "3:2",
              "2:3",
              "21:9"
            ],
            "default": "1:1"
          },
          "size": {
            "title": "Taille",
            "description": "1K ≈ 1 mégapixel, 2K ≈ 4 mégapixels.",
            "type": "string",
            "enum": [
              "1K",
              "2K"
            ],
            "default": "2K"
          },
          "seed": {
            "title": "Seed",
            "description": "Réutilisez le même seed et les mêmes paramètres pour reproduire un résultat. Laissez ce champ vide pour une valeur aléatoire.",
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "title": "Webhook URL",
            "description": "Optional. We POST the finished generation here (signed)."
          }
        },
        "additionalProperties": false
      }
    }
  ],
  "pricing": {
    "unit": "image",
    "notes": [],
    "list_price_source": "official",
    "list_price_label": "Official",
    "tiers": [
      {
        "tier": "1K",
        "detail": "≈1 MP",
        "price_usd": 0.03325,
        "list_price_usd": 0.045,
        "discount_pct": 26
      },
      {
        "tier": "2K",
        "detail": "≈4 MP",
        "price_usd": 0.0665,
        "list_price_usd": 0.09,
        "discount_pct": 26
      }
    ]
  },
  "deprecation": null,
  "upcoming_price_changes": []
}

Limité à un seul point de terminaison pour alléger l’exemple.

Dépréciation et changements de tarifs#

Nous annonçons à l’avance les hausses de prix et le retrait des modèles : au moins 14 jours avant une hausse (davantage si votre contrat le prévoit) et 14 à 30 jours avant le retrait d’un modèle. Nous en informons par e-mail tous les clients qui l’ont utilisé au cours des 90 derniers jours et publions l’annonce sur journal des changements (flux RSS). L’API fournit les mêmes informations pour que votre code et vos agents puissent réagir :

deprecationobject | null: Sur Lister les modèles et Récupérer un modèle. Renseigné lorsque le retrait d’un modèle est programmé : sunset_at (ISO 8601 ; à partir de cette date, les requêtes renvoient 410 model_delisted et rien n’est facturé), replacement (identifiants des modèles de remplacement recommandés, du meilleur au moins adapté), reason, announced_at et info_url. Sinon, null.
upcoming_price_changesarray: Changements de prix programmés par palier, pas encore appliqués : tier, effective_at, current_price_usd et le nouveau tarif price_usd par unit. Les requêtes envoyées avant le effective_at sont facturées au tarif actuel ; le prix d’une génération ne change jamais après son envoi. Vide si aucun changement n’est programmé.
warningsarray: Sur Envoyer une génération et Obtenir un devis, uniquement s’il y a une information à signaler : model_deprecated (avec sunset_at et replacement) ou price_change_scheduled pour le palier de la requête (avec effective_at et le nouveau tarif price_usd). Chaque élément comprend un champ message explicite et un champ info_url.

Requête

curl https://cheapergen.com/api/v1/models/bytedance/seedance-2.0-fast

Réponse · 200 OK

{
  "id": "bytedance/seedance-2.0-fast",
  "object": "model",
  "…": "…",
  "deprecation": {
    "sunset_at": "2026-11-20T00:00:00.000Z",
    "replacement": [
      "bytedance/seedance-2.0-fast"
    ],
    "reason": "Le développeur retire ce modèle.",
    "announced_at": "2026-10-21T09:30:00.000Z",
    "info_url": "https://cheapergen.com/changelog#cm2x7k9"
  },
  "upcoming_price_changes": [
    {
      "tier": "720p",
      "effective_at": "2026-11-04T00:00:00.000Z",
      "unit": "second",
      "current_price_usd": 0.08,
      "price_usd": 0.092,
      "change_pct": 15,
      "info_url": "https://cheapergen.com/changelog#cm2x8a1"
    }
  ]
}

En-têtes Deprecation et Sunset#

Pendant la période précédant le retrait d’un modèle, ses réponses — POST /run, POST /quote et GET /models/{vendor}/{model} — contiennent les en-têtes standards, que les clients HTTP et les passerelles API peuvent enregistrer ou utiliser pour déclencher une alerte :

En-têtes de réponse

Deprecation: @1792575000
Sunset: Fri, 20 Nov 2026 00:00:00 GMT
Link: <https://cheapergen.com/changelog#cm2x7k9>; rel="deprecation"; type="text/html", <https://cheapergen.com/changelog#cm2x7k9>; rel="sunset"; type="text/html"

Deprecation (RFC 9745) correspond à la date d’annonce du retrait, sous forme d’horodatage Unix ; Sunset (RFC 8594) indique quand les requêtes cessent d’être traitées. Le changement se fait sur une seule ligne : envoyez la même requête au point de terminaison du modèle de remplacement (consultez son schéma d’entrée pour connaître les différences d’options).

Avec MCP, list_models et get_model contiennent les mêmes champs deprecation et upcoming_price_changes, ainsi qu’un résumé notice en une ligne. Les agents peuvent ainsi prévenir l’utilisateur avant de s’appuyer sur un modèle en cours de retrait.

Obtenir un devis#

POST/api/v1/quote/{endpoint}Public · sans authentification

Évalue le prix d’une entrée sans lancer de génération. Seuls les champs qui déterminent le prix (résolution, durée, taille, nombre d’images, etc.) sont pris en compte ; les champs de contenu tels que prompt et les URL de référence sont ignorés, et les valeurs omises prennent leur valeur par défaut. available vaut false si le modèle n’accepte temporairement pas de générations.

Les vidéos de référence ajoutent des secondes facturées. Pour les inclure, transmettez reference_video_durations (durée en secondes, une valeur par clip) à titre indicatif ; /run mesure les fichiers réels et réserve le montant correspondant. Voir Facturation.

Requête

curl -X POST https://cheapergen.com/api/v1/quote/bytedance/seedance-2.0-fast/text-to-video \
  -H "Content-Type: application/json" \
  -d '{"aspect_ratio":"16:9","resolution":"720p","duration":5}'

Réponse · 200 OK

{
  "amount_usd": 0.4494,
  "list_usd": 0.6048,
  "list_price_source": "official",
  "list_price_label": "Official",
  "discount_pct": 26,
  "available": true,
  "currency": "usd"
}

Envoyez votre clé API pour obtenir votre tarif personnalisé. Si votre compte en possède un — un tarif contractuel ou un forfait Pro ou Max — le devis inclut aussi custom_price: true et standard_amount_usd (le tarif habituel), ainsi que volume_level (1 ou 2) si le forfait Pro (1) ou Max (2) l’a fixé.

Récupérer les informations du compte#

GET/api/v1/accountClé API requise

Renvoie votre solde et vos paramètres de recharge automatique. balance_usd correspond au montant disponible ; image_credit_usd est un crédit réservé aux images (par exemple, un crédit de bienvenue), utilisé pour payer les modèles d’image avant votre solde, jamais les vidéos ; reserved_usd est le montant réservé sur votre solde pour les générations en cours. Voir Facturation et crédits.

Requête

curl https://cheapergen.com/api/v1/account \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "object": "account",
  "email": "you@company.com",
  "balance_usd": 42.5,
  "image_credit_usd": 0,
  "reserved_usd": 1.2,
  "auto_topup": {
    "enabled": true,
    "threshold_usd": 10,
    "amount_usd": 50
  },
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

limits indique les limites d'API de votre compte et le nombre de ses générations en cours ; si le compte n'a aucune limite, elles valent null, avec unlimited: true. Voir Limites de débit.

Obtenir vos tarifs#

GET/api/v1/account/pricingClé API requise

Renvoie votre forfait mensuel, le niveau de volume auquel il donne accès et votre tarif personnalisé par palier, à côté du tarif standard. Ajoutez ?model={vendor}/{model} pour un modèle. Le paiement à l’usage ne nécessite aucun forfait : dans ce cas, plan vaut null et custom vaut false. Voir Forfaits mensuels.

customboolean: true si un forfait Pro ou Max, ou un tarif contractuel, réduit l’un de vos tarifs.
planobject | null: Votre forfait mensuel : { "id", "status" }, par ex. pro et active (starter, pro ou max). null sans forfait.
volumeobject: level : 1 si Pro est actif, 2 si Max est actif, sinon null.
rulesarray: Vos tarifs contractuels, actifs et programmés : scope, status, discount_pct ou unit_price_usd, starts_at, ends_at et un description lisible.
modelsarray: Tous les modèles couverts par votre forfait ou une règle : id, name, unit et tiers — chacun avec price_usd (votre tarif), standard_price_usd, custom, volume_level (si le forfait l’a défini) et available.

Requête

curl "https://cheapergen.com/api/v1/account/pricing?model=bytedance/seedance-2.0-fast" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Réponse · 200 OK

{
  "object": "customer_pricing",
  "custom": true,
  "plan": {
    "id": "pro",
    "status": "active"
  },
  "volume": {
    "level": 1
  },
  "rules": [],
  "models": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "name": "Seedance 2.0 Fast",
      "unit": "second",
      "tiers": [
        "…"
      ]
    }
  ]
}

Téléverser un fichier#

POST/api/v1/uploadsClé API requise

Téléverse un fichier que vous pouvez transmettre comme URL d’entrée : première image, image de référence, vidéo de référence ou extrait audio de référence. Vous pouvez aussi transmettre directement n’importe quelle URL HTTPS publique au lieu de téléverser le fichier.

Type	Formats	Taille max.
Image	PNG, JPEG, WebP, GIF	20 Mo
Vidéo	MP4, MOV	50 Mo
Audio	MP3, WAV, M4A (les modèles acceptent actuellement MP3 ou WAV)	15 Mo

Téléversement direct (recommandé)#

Envoyez un JSON contenant le filename, le content_type et le size du fichier, en octets. Vous recevez une URL upload_url à durée de vie limitée ; envoyez les octets bruts vers cette URL en utilisant la méthode HTTP PUT, avec exactement la valeur renvoyée pour le champ headers, puis utilisez url comme entrée. Le fichier est envoyé directement vers le stockage : aucune limite de taille de requête ne s’applique en dehors des limites indiquées ci-dessus. L’URL d’envoi expire au bout de 15 minutes. size doit être la taille exacte du fichier en octets : envoyez en PUT exactement ce nombre d’octets avec un Content-Length (pas de corps chunked ni en streaming). Le stockage répond 403 à tout le reste.

Requête

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"choreo.mp4","content_type":"video/mp4","size":8421903}'

Réponse · 201 Created

{
  "object": "upload",
  "method": "PUT",
  "upload_url": "https://storage.example.com/media/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "bytes": 8421903,
  "expires_at": "2026-10-15T09:36:04.000Z"
}

Envoyer ensuite les octets

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @choreo.mp4

Téléversement multipart#

Vous pouvez aussi envoyer multipart/form-data avec un champ file ; nous stockons alors le fichier pour vous et renvoyons 201 Created avec le champ url. Les octets transitent par notre API, dont le corps des requêtes est limité à environ 4.5 Mo : pour les fichiers plus volumineux, utilisez l’envoi direct. Si l’envoi direct n’est pas disponible sur un déploiement, la requête JSON renvoie 501 direct_upload_unavailable ; utilisez alors l’envoi multipart.

Requête

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -F "file=@first-frame.png"

Réponse · 201 Created

{
  "object": "upload",
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "kind": "image",
  "content_type": "image/png",
  "bytes": 1834221
}

Utiliser une image téléversée#

Transmettez l’URL renvoyée dans le champ image d’un point de terminaison de conversion d’image en vidéo ou de retouche :

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "La caméra avance tandis qu’elle se retourne et sourit ; ses cheveux bougent dans le vent",
  "image_url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Références par modèle

Chaque modèle possède sa propre page API, qui indique pour chaque champ son type, sa valeur par défaut et les valeurs autorisées, avec des exemples à copier-coller — consultez la page liste des modèles pour commencer.

Quelque chose n’est pas clair ou manque ? Écrivez à support@cheapergen.com : nous lisons tous les messages.