Documentation

Référence API

Créer une tâche image persistante

POST/v1/image-tasks

quote_id valide et Idempotency-Key doivent correspondre. Exécution unique en arrière-plan avec règlement/archivage ; aucune répétition aveugle pour unknown ou billing_review. Requête de 128 KiB maximum, champs inconnus refusés.

Du devis au résultat

Préparez d'abord des entrées valides, obtenez un devis, puis après confirmation explicite, envoyez quote_id avec les paramètres d'origine. Le devis ne verrouille pas les ressources ; leur suppression avant confirmation peut faire échouer la création. Corrigez alors les entrées et redemandez un devis.

L'application doit enregistrer la clé de requête métier et l'ID de tâche. Après déconnexion, récupérez avec la clé d'origine au lieu de régénérer face à un état inconnu. Même en cas de réussite partielle, vérifiez chaque résultat et sa sauvegarde avant de décider du téléchargement. Voir Tâches asynchrones et idempotence.

Authentification et autorisations

Utilisez votre clé GloopAPI actuelle. Les modèles, capacités et autorisations disponibles dépendent de son catalogue et de la documentation du point de terminaison.

Authorization: Bearer $GLOOP_API_KEY

Schémas d'authentification : BearerAuth

Requête

En-têtes de requête

  • Idempotency-KeystringObligatoire

    Conserve l'intention initiale sous la même Key. Après interruption réseau, consultez d'abord la récupération ; aucune répétition aveugle pour un état inconnu.

    Longueur minimale
    1
    Longueur maximale
    191

Corps de requête · application/json

Type
object
Champs obligatoires
modelpromptsize
Propriétés supplémentaires
false

Corps de requête obligatoire

  • modelstringObligatoire

    ID public du modèle dans le catalogue de la Key actuelle.

    Longueur maximale
    191
  • promptstringObligatoire

    Non vide, au plus 32000 octets UTF-8. OpenAPI maxLength compte les caractères ; aucun faux plafond de caractères n'est défini.

  • sizestringObligatoire

    Dimension renvoyée par image-models pour le modèle choisi ; capacités et dimensions validées séparément par modèle.

  • nintegerFacultatif

    Omis ou 0 est normalisé à 1. Le maximum réel est max_n de image-models ; le plafond global n'est pas une capacité du modèle.

    Valeur par défaut
    1
    Minimum
    1
    Maximum
    6
  • referencesarrayFacultatif

    Chaque élément choisit uniquement file_id, asset_id ou url ; quantité effective selon max_references.

    Nombre maximal d'éléments
    14
    Sous-champs de references (1)
    • []objectFacultatif
      Sous-champs de [] (3)
      • file_idstringFacultatif

        ID public du fichier hébergé du même compte et de la même Key.

      • asset_idstringFacultatif

        ID de ressource téléversée du même compte et de la même Key.

      • urlstringFacultatif

        URL HTTPS publique, sans userinfo ni fragment ; soumise aux contrôles SSRF.

        Format
        "uri"
      Branche oneOf 1

      Obligatoire dans cette branche : file_id

      Branche oneOf 2

      Obligatoire dans cette branche : asset_id

      Branche oneOf 3

      Obligatoire dans cette branche : url

  • source_task_idstringFacultatif

    Tâche source facultative de la même Key, uniquement pour la traçabilité ; ne remplace pas references.

    Longueur maximale
    64
  • quote_idstringFacultatif

    À la création, devis valide correspondant à la requête ; ignoré lors d'une demande de devis.

Réponses et erreurs

HTTP 202

Tâche image persistante créée

application/json

Type
object
Champs obligatoires
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringObligatoire

    ID public du modèle dans le catalogue de la Key actuelle.

  • promptstringObligatoire

    Prompt de génération.

  • sizestringObligatoire

    Dimension renvoyée par image-models pour le modèle choisi ; capacités et dimensions validées séparément par modèle.

  • nintegerObligatoire

    Nombre d'images demandé, toujours soumis au plafond du modèle.

  • referencesarrayObligatoire

    Liste des images de référence pour la génération.

    Sous-champs de references (1)
    • []objectFacultatif
      Sous-champs de [] (3)
      • file_idstringFacultatif

        ID public du fichier hébergé du même compte et de la même Key.

      • asset_idstringFacultatif

        ID de ressource téléversée du même compte et de la même Key.

      • urlstringFacultatif

        URL HTTPS publique, sans userinfo ni fragment ; soumise aux contrôles SSRF.

        Format
        "uri"
      Branche oneOf 1

      Obligatoire dans cette branche : file_id

      Branche oneOf 2

      Obligatoire dans cette branche : asset_id

      Branche oneOf 3

      Obligatoire dans cette branche : url

  • source_task_idstringFacultatif

    ID public de la tâche source, uniquement pour traçabilité.

  • quote_idstringFacultatif

    ID public du devis ; doit respecter les liens prix/requête à la création.

  • idstringObligatoire

    Identifiant public de l'objet, utilisé dans son chemin de détails.

  • statusstringObligatoire

    unknown n'est pas répété automatiquement ; la pré-réservation comptable peut rester pending.

    Énumération
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerObligatoire

    Date de création en secondes Unix.

  • updated_atintegerObligatoire

    Dernière mise à jour en secondes Unix.

  • reserved_quotaintegerObligatoire

    Réservation en unités quota de la plateforme, pas en dollars.

  • final_quotaintegerObligatoire

    Coût final en unités quota de la plateforme ; null signifie non déterminé.

  • billing_statusstringObligatoire

    État de réservation/règlement/remboursement, à vérifier séparément de la tâche et de l'archivage.

  • error_codestringFacultatif

    Code d'erreur public utilisable pour choisir une branche de traitement.

  • error_messagestringFacultatif

    Explication utilisateur issue de la classification publique des erreurs.

  • resultsarrayObligatoire

    Éléments de sortie générés ; archivage indépendant pour chacun.

    Sous-champs de results (1)
    • []objectFacultatif
      Sous-champs de [] (7)
      • file_idstringFacultatif

        ID public du fichier hébergé du même compte et de la même Key.

      • storage_statusstringFacultatif

        État d'archivage du fichier ; le téléchargement hébergé est garanti seulement après ready.

      • storage_errorstringFacultatif

        Catégorie publique de l'échec d'archivage du fichier.

      • expires_atintegerFacultatif

        Expiration en secondes Unix ; 0 signifie aucune échéance fixe.

      • urlstringFacultatif

        URL d'accès au résultat ou à la référence ; les URL signées sont temporaires.

      • b64_jsonstringFacultatif

        Chaîne Base64 de l'image ; ne la demandez pas comme une URL.

      • revised_promptstringFacultatif

        Prompt révisé renvoyé par le service, le cas échéant.

HTTP 400

Champs ou paramètres de requête invalides.

application/json

Type
object
Champs obligatoires
error

HTTP 401

Key absente, invalide, expirée ou révoquée.

application/json

Type
object
Champs obligatoires
error

HTTP 403

Autorisations IP, compte, modèle ou outil insuffisantes.

application/json

Type
object
Champs obligatoires
error

HTTP 404

Objet/capacité indisponible ou fonctionnalité désactivée.

application/json

Type
object
Champs obligatoires
error

HTTP 409

Conflit d'idempotence/devis, objet non prêt ou encore référencé.

application/json

Type
object
Champs obligatoires
error

HTTP 429

Limitation de débit des requêtes/de la file.

application/json

Type
object
Champs obligatoires
error

HTTP 500

Défaillance interne d'authentification ou de stockage des données.

application/json

Type
object
Champs obligatoires
error

HTTP 503

Service, tarification ou stockage indisponible.

application/json

Type
object
Champs obligatoires
error