Documentation

API reference

Create a persistent image task

POST/v1/image-tasks

A valid quote_id and Idempotency-Key must match. Background processing executes once and settles/archives. Never blindly resend unknown or billing_review. Requests are limited to 128 KiB; unknown fields are rejected.

From quote to result

Prepare usable inputs first, obtain a quote, and after explicit confirmation submit quote_id with the original parameters. Quotes do not lock assets. If a user deletes an asset before confirmation, creation may fail; correct the input and obtain a new quote.

Applications should retain both the business request key and task ID. Recover with the original key after a client disconnect; do not regenerate because the status is unknown. For partial success, inspect each result and its saving status separately before deciding whether to download. See Asynchronous tasks and idempotency.

Authentication and permissions

Use your current GloopAPI key. Available models, capabilities and permissions depend on its catalog and the endpoint documentation.

Authorization: Bearer $GLOOP_API_KEY

Authentication schemes: BearerAuth

Request

Request headers

  • Idempotency-KeystringRequired

    Retain the original request intent with the same key. After a network interruption, query recovery first; never blindly resend unknown states.

    Minimum length
    1
    Maximum length
    191

Request body · application/json

Type
object
Required fields
modelpromptsize
Additional properties
false

Request body required

  • modelstringRequired

    Public model ID from the current key's catalog.

    Maximum length
    191
  • promptstringRequired

    Nonempty, at most 32000 UTF-8 bytes. OpenAPI maxLength counts characters, so no artificial character limit is specified.

  • sizestringRequired

    Size value returned by the selected image-models entry; capabilities and sizes are validated per model.

  • nintegerOptional

    Omitted or 0 values normalize to 1. The actual maximum is max_n from image-models; do not treat the global maximum as a model capability.

    Default value
    1
    Minimum
    1
    Maximum
    6
  • referencesarrayOptional

    Select only one of file_id, asset_id, or url per item; actual quantity is governed by max_references.

    Maximum items
    14
    references child fields (1)
    • []objectOptional
      [] child fields (3)
      • file_idstringOptional

        Public ID of a managed file for the same account and key.

      • asset_idstringOptional

        Upload asset ID for the same account and key.

      • urlstringOptional

        Public HTTPS URL; userinfo and fragment are prohibited, and SSRF checks apply.

        Format
        "uri"
      oneOf branch 1

      Required in this branch: file_id

      oneOf branch 2

      Required in this branch: asset_id

      oneOf branch 3

      Required in this branch: url

  • source_task_idstringOptional

    Optional source task belonging to the same key, for provenance only; does not replace references.

    Maximum length
    64
  • quote_idstringOptional

    Must be valid and match the request when creating a task; ignored in quote requests.

Responses and errors

HTTP 202

Persistent image task created successfully

application/json

Type
object
Required fields
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringRequired

    Public model ID from the current key's catalog.

  • promptstringRequired

    Generation prompt.

  • sizestringRequired

    Size value returned by the selected image-models entry; capabilities and sizes are validated per model.

  • nintegerRequired

    Requested output image count, still constrained by the selected model's maximum.

  • referencesarrayRequired

    List of reference images for generation.

    references child fields (1)
    • []objectOptional
      [] child fields (3)
      • file_idstringOptional

        Public ID of a managed file for the same account and key.

      • asset_idstringOptional

        Upload asset ID for the same account and key.

      • urlstringOptional

        Public HTTPS URL; userinfo and fragment are prohibited, and SSRF checks apply.

        Format
        "uri"
      oneOf branch 1

      Required in this branch: file_id

      oneOf branch 2

      Required in this branch: asset_id

      oneOf branch 3

      Required in this branch: url

  • source_task_idstringOptional

    Public source task ID, for provenance only.

  • quote_idstringOptional

    Public quote ID; must satisfy price and request binding on creation.

  • idstringRequired

    Public identifier of this object, used for its corresponding detail path.

  • statusstringRequired

    unknown is not automatically resubmitted; reserved billing may still be pending.

    Enum
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerRequired

    Creation time in Unix seconds.

  • updated_atintegerRequired

    Last update time in Unix seconds.

  • reserved_quotaintegerRequired

    Reserved quota in platform quota units, not a USD amount.

  • final_quotaintegerRequired

    Final charge in platform quota units; null means not yet determined.

  • billing_statusstringRequired

    Reservation/settlement/refund status; check separately from task and archival status.

  • error_codestringOptional

    Public error code usable for branching logic.

  • error_messagestringOptional

    User-facing description processed through public error classification.

  • resultsarrayRequired

    Generated output items; each item's archival status is independent.

    results child fields (1)
    • []objectOptional
      [] child fields (7)
      • file_idstringOptional

        Public ID of a managed file for the same account and key.

      • storage_statusstringOptional

        File archival status; managed downloads are only guaranteed after ready.

      • storage_errorstringOptional

        Public category for file archival failure.

      • expires_atintegerOptional

        Expiration in Unix seconds; 0 means no fixed expiration.

      • urlstringOptional

        Access URL for a result or reference; signed URLs are only valid briefly.

      • b64_jsonstringOptional

        Image Base64 string; do not request it as a URL.

      • revised_promptstringOptional

        Revised prompt returned by the service, if any.

HTTP 400

Invalid request fields or parameters.

application/json

Type
object
Required fields
error

HTTP 401

The key is missing, invalid, expired, or revoked.

application/json

Type
object
Required fields
error

HTTP 403

Insufficient IP, account, model, or tool permissions.

application/json

Type
object
Required fields
error

HTTP 404

Object/capability unavailable, or feature switch disabled.

application/json

Type
object
Required fields
error

HTTP 409

Idempotency/quote conflict, object not ready, or still referenced.

application/json

Type
object
Required fields
error

HTTP 429

Request/queue rate limit.

application/json

Type
object
Required fields
error

HTTP 500

Internal authentication or data storage failure.

application/json

Type
object
Required fields
error

HTTP 503

Service, pricing, or storage unavailable.

application/json

Type
object
Required fields
error