文档

API 参考

创建持久图像任务

POST/v1/image-tasks

有效 quote_id 与 Idempotency-Key 必须匹配。后台执行一次并结算/归档；unknown 或 billing_review 禁止盲重发。请求最多 128 KiB，拒绝未知字段。

从报价到结果

先准备可用输入，再获取报价，明确确认后将 quote_id 与原参数共同提交。报价不锁定资产；用户在确认前删除资产可能使创建失败，这时应修正输入重新报价。

应用应同时保存业务请求键与任务 ID。客户端掉线后按原键恢复，不因未知状态重新生成。部分成功也要分别检查每张结果及保存状态，再决定是否下载，见异步任务与幂等。

鉴权与权限

使用当前 GloopAPI Key。模型、功能与权限以当前 Key 的目录及接口说明为准。

Authorization: Bearer $GLOOP_API_KEY

鉴权方案： BearerAuth

请求

请求头

  • Idempotency-Keystring必填

    同 Key 保存原请求意图；网络中断先恢复查询，未知状态禁止盲重发。

    最短长度
    1
    最长长度
    191

请求体 · application/json

类型
object
必填字段
modelpromptsize
额外属性
false

请求体必填

  • modelstring必填

    当前 Key 目录中的公开模型 ID。

    最长长度
    191
  • promptstring必填

    非空，按 UTF-8 字节最多 32000；OpenAPI maxLength 是字符，故不伪造字符上限。

  • sizestring必填

    所选 image-models 返回的尺寸值；能力及尺寸按模型分别校验。

  • ninteger选填

    省略或 0 归一为 1。实际上限取 image-models 的 max_n，不能将全局上限当模型能力。

    默认值
    1
    最小值
    1
    最大值
    6
  • referencesarray选填

    每项仅选 file_id、asset_id、url 之一；实际数量取 max_references。

    最多项数
    14
    references 子字段（1）
    • []object选填
      [] 子字段（3）
      • file_idstring选填

        同账户同 Key 的托管文件公开 ID。

      • asset_idstring选填

        同账户同 Key 的上传资产 ID。

      • urlstring选填

        公开 HTTPS URL，不允许 userinfo 或 fragment；受 SSRF 校验。

        格式
        "uri"
      oneOf 分支 1

      分支必填： file_id

      oneOf 分支 2

      分支必填： asset_id

      oneOf 分支 3

      分支必填： url

  • source_task_idstring选填

    可选的同 Key 来源任务，仅追溯来源，不代替 references。

    最长长度
    64
  • quote_idstring选填

    创建任务时必须是有效且匹配请求的报价；报价请求中忽略。

响应与错误

HTTP 202

创建持久图像任务成功

application/json

类型
object
必填字段
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstring必填

    当前 Key 目录中的公开模型 ID。

  • promptstring必填

    生成提示词。

  • sizestring必填

    所选 image-models 返回的尺寸值；能力及尺寸按模型分别校验。

  • ninteger必填

    请求输出张数，仍受所选模型上限约束。

  • referencesarray必填

    生成引用图片列表。

    references 子字段（1）
    • []object选填
      [] 子字段（3）
      • file_idstring选填

        同账户同 Key 的托管文件公开 ID。

      • asset_idstring选填

        同账户同 Key 的上传资产 ID。

      • urlstring选填

        公开 HTTPS URL，不允许 userinfo 或 fragment；受 SSRF 校验。

        格式
        "uri"
      oneOf 分支 1

      分支必填： file_id

      oneOf 分支 2

      分支必填： asset_id

      oneOf 分支 3

      分支必填： url

  • source_task_idstring选填

    来源任务公开 ID，仅用于追溯。

  • quote_idstring选填

    报价公开 ID，创建时必须符合价格与请求绑定。

  • idstring必填

    该对象的公开标识符；用于对应详情路径。

  • statusstring必填

    unknown 不自动重发，预扣账务可能仍 pending。

    枚举
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atinteger必填

    Unix 秒创建时间。

  • updated_atinteger必填

    Unix 秒最后更新时间。

  • reserved_quotainteger必填

    以平台 quota 单位表示的预留额度，不是美元数。

  • final_quotainteger必填

    以平台 quota 单位表示的最终费用；null 表示尚未确定。

  • billing_statusstring必填

    预留/结算/退回状态，与任务及归档状态分别检查。

  • error_codestring选填

    可用于分支处理的公开错误码。

  • error_messagestring选填

    经过公开错误分类的用户说明。

  • resultsarray必填

    生成输出项；各项归档状态独立。

    results 子字段（1）
    • []object选填
      [] 子字段（7）
      • file_idstring选填

        同账户同 Key 的托管文件公开 ID。

      • storage_statusstring选填

        文件归档状态，ready 后才保证托管下载可用。

      • storage_errorstring选填

        文件归档失败的公开分类。

      • expires_atinteger选填

        Unix 秒有效期，0 表示不按固定时间到期。

      • urlstring选填

        结果或引用的访问 URL；签名 URL 仅短时有效。

      • b64_jsonstring选填

        图片 Base64 字符串；不要当成 URL 请求。

      • revised_promptstring选填

        返回的修订提示词（若有）。

HTTP 400

请求字段或参数无效。

application/json

类型
object
必填字段
error

HTTP 401

Key 缺失、无效、过期或已撤销。

application/json

类型
object
必填字段
error

HTTP 403

IP、账户、模型或工具权限不足。

application/json

类型
object
必填字段
error

HTTP 404

对象/能力不可用，或功能开关关闭。

application/json

类型
object
必填字段
error

HTTP 409

幂等/报价冲突、对象未准备或仍被引用。

application/json

类型
object
必填字段
error

HTTP 429

请求/队列限流。

application/json

类型
object
必填字段
error

HTTP 500

鉴权或数据存储内部失败。

application/json

类型
object
必填字段
error

HTTP 503

服务、定价或存储不可用。

application/json

类型
object
必填字段
error