Documentation

API reference

Import an HTTPS reference image

POST/v1/image-assets/import

When uploads are disabled, the route returns 404 directly. A single JSON object is required; unknown fields are rejected and the body is limited to 8192 bytes. Failed or unready imports must not be treated as generation retries.

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
url
Additional properties
false

Request body required

  • urlstringRequired

    Public HTTPS image URL, subject to SSRF and image content validation.

    Format
    "uri"

Responses and errors

HTTP 200

HTTPS reference image imported successfully

application/json

Type
object
Required fields
idmime_typesize_byteswidthheightexpires_at
  • file_idstringOptional

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

  • idstringRequired

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

  • mime_typestringRequired

    Verified file MIME type.

  • size_bytesintegerRequired

    File size in bytes.

  • widthintegerRequired

    Image width in pixels.

  • heightintegerRequired

    Image height in pixels.

  • expires_atintegerRequired

    Unix seconds; 0 means no fixed expiration. Uploads are associated with managed files; reads require the same account and key.

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