Documentación

Referencia de API

Crear tarea de imagen persistente

POST/v1/image-tasks

quote_id válido e Idempotency-Key deben coincidir. Ejecución única en segundo plano con liquidación/archivado; no reenvíes a ciegas unknown o billing_review. Máximo 128 KiB, sin campos desconocidos.

De la cotización al resultado

Prepara entradas utilizables, obtén una cotización y, tras confirmar explícitamente, envía quote_id junto con los parámetros originales. La cotización no bloquea recursos; si el usuario elimina uno antes de confirmar, la creación puede fallar. Corrige la entrada y vuelve a cotizar.

Guarda tanto la clave de solicitud de negocio como el ID de tarea. Tras una desconexión, recupera con la clave original; no regeneres por un estado desconocido. Ante éxito parcial, comprueba cada resultado y su guardado antes de descargar. Consulta Tareas asíncronas e idempotencia.

Autenticación y permisos

Usa tu clave actual de GloopAPI. Los modelos, capacidades y permisos dependen de su catálogo y de la documentación del endpoint.

Authorization: Bearer $GLOOP_API_KEY

Esquemas de autenticación: BearerAuth

Solicitud

Encabezados de solicitud

  • Idempotency-KeystringObligatorio

    Conserva la intención original con la misma clave; tras una interrupción, consulta recuperación primero. No reenvíes a ciegas estados desconocidos.

    Longitud mínima
    1
    Longitud máxima
    191

Cuerpo de solicitud · application/json

Tipo
object
Campos obligatorios
modelpromptsize
Propiedades adicionales
false

Cuerpo de solicitud obligatorio

  • modelstringObligatorio

    ID público de modelo del catálogo de la clave actual.

    Longitud máxima
    191
  • promptstringObligatorio

    No vacío, máximo 32000 bytes UTF-8; maxLength de OpenAPI cuenta caracteres, por eso no se inventa un máximo de caracteres.

  • sizestringObligatorio

    Tamaño devuelto por image-models seleccionado; capacidades y tamaños se validan por modelo.

  • nintegerOpcional

    Omitido o 0 se normaliza a 1. Límite real: max_n de image-models; el máximo global no es capacidad del modelo.

    Valor predeterminado
    1
    Mínimo
    1
    Máximo
    6
  • referencesarrayOpcional

    En cada elemento, solo uno de file_id, asset_id o url; cantidad según max_references.

    Máximo de elementos
    14
    Campos secundarios de references (1)
    • []objectOpcional
      Campos secundarios de [] (3)
      • file_idstringOpcional

        ID público de archivo gestionado de la misma cuenta y clave.

      • asset_idstringOpcional

        ID de recurso subido de la misma cuenta y clave.

      • urlstringOpcional

        URL HTTPS pública; no admite userinfo ni fragment y está sujeta a comprobaciones SSRF.

        Formato
        "uri"
      Rama oneOf 1

      Obligatorio en esta rama: file_id

      Rama oneOf 2

      Obligatorio en esta rama: asset_id

      Rama oneOf 3

      Obligatorio en esta rama: url

  • source_task_idstringOpcional

    Tarea de origen opcional de la misma clave, solo para trazabilidad; no sustituye references.

    Longitud máxima
    64
  • quote_idstringOpcional

    Al crear debe ser una cotización válida y coincidente con la solicitud; se ignora al cotizar.

Respuestas y errores

HTTP 202

Tarea de imagen persistente creada correctamente

application/json

Tipo
object
Campos obligatorios
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringObligatorio

    ID público de modelo del catálogo de la clave actual.

  • promptstringObligatorio

    Prompt de generación.

  • sizestringObligatorio

    Tamaño devuelto por image-models seleccionado; capacidades y tamaños se validan por modelo.

  • nintegerObligatorio

    Cantidad solicitada de imágenes, sujeta al máximo del modelo.

  • referencesarrayObligatorio

    Lista de imágenes de referencia para generar.

    Campos secundarios de references (1)
    • []objectOpcional
      Campos secundarios de [] (3)
      • file_idstringOpcional

        ID público de archivo gestionado de la misma cuenta y clave.

      • asset_idstringOpcional

        ID de recurso subido de la misma cuenta y clave.

      • urlstringOpcional

        URL HTTPS pública; no admite userinfo ni fragment y está sujeta a comprobaciones SSRF.

        Formato
        "uri"
      Rama oneOf 1

      Obligatorio en esta rama: file_id

      Rama oneOf 2

      Obligatorio en esta rama: asset_id

      Rama oneOf 3

      Obligatorio en esta rama: url

  • source_task_idstringOpcional

    ID público de tarea de origen, solo para trazabilidad.

  • quote_idstringOpcional

    ID público de cotización; debe coincidir con precio y solicitud al crear.

  • idstringObligatorio

    Identificador público del objeto, usado en su ruta de detalles.

  • statusstringObligatorio

    unknown no se reenvía automáticamente; el cargo reservado puede seguir pending.

    Enumeración
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerObligatorio

    Fecha de creación en segundos Unix.

  • updated_atintegerObligatorio

    Última actualización en segundos Unix.

  • reserved_quotaintegerObligatorio

    Reserva en unidades quota de la plataforma, no en USD.

  • final_quotaintegerObligatorio

    Cargo final en unidades quota de la plataforma; null indica que aún no se ha determinado.

  • billing_statusstringObligatorio

    Estado de reserva/liquidación/devolución; compruébalo aparte de tarea y archivado.

  • error_codestringOpcional

    Código público de error para decisiones de flujo.

  • error_messagestringOpcional

    Descripción para usuario mediante clasificación pública de errores.

  • resultsarrayObligatorio

    Elementos generados; archivado independiente por elemento.

    Campos secundarios de results (1)
    • []objectOpcional
      Campos secundarios de [] (7)
      • file_idstringOpcional

        ID público de archivo gestionado de la misma cuenta y clave.

      • storage_statusstringOpcional

        Estado de archivado; descarga gestionada garantizada solo tras ready.

      • storage_errorstringOpcional

        Categoría pública de fallo de archivado.

      • expires_atintegerOpcional

        Caducidad en segundos Unix; 0 indica que no hay caducidad fija.

      • urlstringOpcional

        URL de acceso al resultado o referencia; firmadas solo válidas temporalmente.

      • b64_jsonstringOpcional

        Cadena Base64 de imagen; no la solicites como URL.

      • revised_promptstringOpcional

        Prompt revisado devuelto por el servicio, si existe.

HTTP 400

Campos o parámetros de solicitud inválidos.

application/json

Tipo
object
Campos obligatorios
error

HTTP 401

La clave falta, no es válida, caducó o fue revocada.

application/json

Tipo
object
Campos obligatorios
error

HTTP 403

Permisos insuficientes de IP, cuenta, modelo o herramienta.

application/json

Tipo
object
Campos obligatorios
error

HTTP 404

Objeto/capacidad no disponible o función desactivada.

application/json

Tipo
object
Campos obligatorios
error

HTTP 409

Conflicto de idempotencia/cotización, objeto no preparado o aún referenciado.

application/json

Tipo
object
Campos obligatorios
error

HTTP 429

Límite de solicitudes/cola.

application/json

Tipo
object
Campos obligatorios
error

HTTP 500

Fallo interno de autenticación o almacenamiento de datos.

application/json

Tipo
object
Campos obligatorios
error

HTTP 503

Servicio, precios o almacenamiento no disponibles.

application/json

Tipo
object
Campos obligatorios
error