Documentação

Referência da API

Criar tarefa de imagem persistente

POST/v1/image-tasks

quote_id válido e Idempotency-Key precisam corresponder. Execução única em segundo plano com liquidação/arquivamento; não reenvie às cegas unknown ou billing_review. Máximo de 128 KiB, sem campos desconhecidos.

Da cotação ao resultado

Prepare entradas utilizáveis, obtenha uma cotação e, após confirmação explícita, envie quote_id com os parâmetros originais. A cotação não bloqueia recursos; se o usuário excluir um antes de confirmar, a criação pode falhar. Corrija a entrada e obtenha outra cotação.

Salve a chave da solicitação de negócio e o ID da tarefa. Após desconexão, recupere com a chave original; não gere novamente por status desconhecido. Em sucesso parcial, confira cada resultado e seu salvamento antes de baixar. Consulte Tarefas assíncronas e idempotência.

Autenticação e permissões

Use sua chave atual do GloopAPI. Modelos, recursos e permissões disponíveis dependem do catálogo da chave e da documentação do endpoint.

Authorization: Bearer $GLOOP_API_KEY

Esquemas de autenticação: BearerAuth

Solicitação

Cabeçalhos da solicitação

  • Idempotency-KeystringObrigatório

    Preserve a intenção original com a mesma chave; após interrupção, consulte a recuperação primeiro. Não reenvie às cegas estados desconhecidos.

    Comprimento mínimo
    1
    Comprimento máximo
    191

Corpo da solicitação · application/json

Tipo
object
Campos obrigatórios
modelpromptsize
Propriedades adicionais
false

Corpo da solicitação obrigatório

  • modelstringObrigatório

    ID público do modelo no catálogo da chave atual.

    Comprimento máximo
    191
  • promptstringObrigatório

    Não vazio, máximo de 32000 bytes UTF-8; maxLength do OpenAPI conta caracteres, por isso não se inventa um máximo de caracteres.

  • sizestringObrigatório

    Tamanho retornado por image-models selecionado; recursos e tamanhos são validados por modelo.

  • nintegerOpcional

    Omitido ou 0 normaliza para 1. Limite real: max_n de image-models; máximo global não é recurso do modelo.

    Valor padrão
    1
    Mínimo
    1
    Máximo
    6
  • referencesarrayOpcional

    Em cada item, apenas um de file_id, asset_id ou url; quantidade conforme max_references.

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

        ID público de arquivo gerenciado da mesma conta e chave.

      • asset_idstringOpcional

        ID de recurso enviado da mesma conta e chave.

      • urlstringOpcional

        URL HTTPS pública; não aceita userinfo nem fragment e passa por verificações SSRF.

        Formato
        "uri"
      Ramificação oneOf 1

      Obrigatório nesta ramificação: file_id

      Ramificação oneOf 2

      Obrigatório nesta ramificação: asset_id

      Ramificação oneOf 3

      Obrigatório nesta ramificação: url

  • source_task_idstringOpcional

    Tarefa de origem opcional da mesma chave, apenas para rastreabilidade; não substitui references.

    Comprimento máximo
    64
  • quote_idstringOpcional

    Na criação, deve ser uma cotação válida e correspondente à solicitação; ignorada em solicitações de cotação.

Respostas e erros

HTTP 202

Tarefa de imagem persistente criada com sucesso

application/json

Tipo
object
Campos obrigatórios
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringObrigatório

    ID público do modelo no catálogo da chave atual.

  • promptstringObrigatório

    Prompt de geração.

  • sizestringObrigatório

    Tamanho retornado por image-models selecionado; recursos e tamanhos são validados por modelo.

  • nintegerObrigatório

    Quantidade de imagens solicitada, sujeita ao máximo do modelo.

  • referencesarrayObrigatório

    Lista de imagens de referência para gerar.

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

        ID público de arquivo gerenciado da mesma conta e chave.

      • asset_idstringOpcional

        ID de recurso enviado da mesma conta e chave.

      • urlstringOpcional

        URL HTTPS pública; não aceita userinfo nem fragment e passa por verificações SSRF.

        Formato
        "uri"
      Ramificação oneOf 1

      Obrigatório nesta ramificação: file_id

      Ramificação oneOf 2

      Obrigatório nesta ramificação: asset_id

      Ramificação oneOf 3

      Obrigatório nesta ramificação: url

  • source_task_idstringOpcional

    ID público da tarefa de origem, só para rastreabilidade.

  • quote_idstringOpcional

    ID público da cotação; deve corresponder ao preço e à solicitação na criação.

  • idstringObrigatório

    Identificador público do objeto, usado na sua rota de detalhes.

  • statusstringObrigatório

    unknown não é reenviado automaticamente; a cobrança reservada pode continuar pending.

    Enumeração
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerObrigatório

    Data de criação em segundos Unix.

  • updated_atintegerObrigatório

    Última atualização em segundos Unix.

  • reserved_quotaintegerObrigatório

    Reserva em unidades quota da plataforma, não em USD.

  • final_quotaintegerObrigatório

    Cobrança final em unidades quota da plataforma; null indica ainda não determinada.

  • billing_statusstringObrigatório

    Status de reserva/liquidação/devolução; confira separadamente da tarefa e do arquivamento.

  • error_codestringOpcional

    Código público de erro para decisões de fluxo.

  • error_messagestringOpcional

    Descrição para o usuário via classificação pública de erros.

  • resultsarrayObrigatório

    Itens gerados; arquivamento independente por item.

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

        ID público de arquivo gerenciado da mesma conta e chave.

      • storage_statusstringOpcional

        Status de arquivamento; download gerenciado garantido apenas após ready.

      • storage_errorstringOpcional

        Categoria pública de falha de arquivamento.

      • expires_atintegerOpcional

        Expiração em segundos Unix; 0 indica ausência de expiração fixa.

      • urlstringOpcional

        URL de acesso ao resultado ou referência; assinadas só valem temporariamente.

      • b64_jsonstringOpcional

        String Base64 da imagem; não a solicite como URL.

      • revised_promptstringOpcional

        Prompt revisado retornado pelo serviço, se houver.

HTTP 400

Campos ou parâmetros de solicitação inválidos.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 401

A chave está ausente, inválida, expirada ou revogada.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 403

Permissões insuficientes de IP, conta, modelo ou ferramenta.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 404

Objeto/recurso indisponível ou função desativada.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 409

Conflito de idempotência/cotação, objeto não pronto ou ainda referenciado.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 429

Limite de solicitações/fila.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 500

Falha interna de autenticação ou armazenamento de dados.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 503

Serviço, preços ou armazenamento indisponíveis.

application/json

Tipo
object
Campos obrigatórios
error
Pronto para criar? Abra console para criar uma chave de API, ou explore recursos.