문서

API 참조

영구 보관 이미지 작업 생성

POST/v1/image-tasks

유효한 quote_id와 Idempotency-Key가 일치해야 합니다. 백그라운드 처리가 한 번 실행하고 정산/보관합니다. unknown 또는 billing_review를 무조건 재전송하지 마세요. 요청은 128 KiB로 제한하며 알 수 없는 필드는 거부합니다.

견적부터 결과까지

먼저 사용 가능한 입력을 준비하고 견적을 받은 뒤 명시적으로 확인하여 원래 매개변수와 함께 quote_id를 제출하세요. 견적은 자산을 잠그지 않습니다. 확인 전에 사용자가 자산을 삭제하면 생성에 실패할 수 있으므로 입력을 수정하고 새 견적을 받으세요.

애플리케이션은 비즈니스 요청 키와 작업 ID를 모두 보관해야 합니다. 클라이언트 연결이 끊기면 원래 키로 복구하고 상태가 불명확하다는 이유로 다시 생성하지 마세요. 일부만 성공한 경우 다운로드를 결정하기 전에 각 결과와 저장 상태를 따로 확인하세요. 비동기 작업과 멱등성을 참고하세요.

인증과 권한

현재 GloopAPI 키를 사용하세요. 사용 가능한 모델, 기능과 권한은 해당 카탈로그와 엔드포인트 문서에 따라 달라집니다.

Authorization: Bearer $GLOOP_API_KEY

인증 방식: BearerAuth

요청

요청 헤더

  • Idempotency-Keystring필수

    동일한 키로 원래 요청 의도를 유지하세요. 네트워크 중단 후 먼저 복구를 조회하고 불명확한 상태를 무조건 재전송하지 마세요.

    최소 길이
    1
    최대 길이
    191

요청 본문 · application/json

유형
object
필수 필드
modelpromptsize
추가 속성
false

요청 본문 필수

  • modelstring필수

    현재 키의 카탈로그에 있는 공개 모델 ID입니다.

    최대 길이
    191
  • promptstring필수

    비어 있지 않아야 하며 최대 32000 UTF-8바이트입니다. 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선택 사항

        동일 계정/키의 관리형 파일 공개 ID입니다.

      • asset_idstring선택 사항

        동일 계정/키의 업로드 자산 ID입니다.

      • urlstring선택 사항

        공개 HTTPS URL입니다. userinfo와 fragment는 금지되며 SSRF 검사가 적용됩니다.

        형식
        "uri"
      oneOf 분기 1

      이 분기의 필수 항목: file_id

      oneOf 분기 2

      이 분기의 필수 항목: asset_id

      oneOf 분기 3

      이 분기의 필수 항목: url

  • source_task_idstring선택 사항

    동일 키 소유의 선택적 원본 작업이며 출처 표시 전용으로 참조를 대체하지 않습니다.

    최대 길이
    64
  • quote_idstring선택 사항

    작업 생성 시 유효하고 요청과 일치해야 하며 견적 요청에서는 무시합니다.

응답과 오류

HTTP 202

영구 보관 이미지 작업 생성 성공

application/json

유형
object
필수 필드
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstring필수

    현재 키의 카탈로그에 있는 공개 모델 ID입니다.

  • promptstring필수

    생성 프롬프트입니다.

  • sizestring필수

    선택한 image-models 항목이 반환한 크기 값이며 기능과 크기는 모델별로 검증합니다.

  • ninteger필수

    요청한 출력 이미지 수이며 선택한 모델의 최댓값을 계속 적용합니다.

  • referencesarray필수

    생성에 사용할 참조 이미지 목록입니다.

    references 하위 필드(1)
    • []object선택 사항
      [] 하위 필드(3)
      • file_idstring선택 사항

        동일 계정/키의 관리형 파일 공개 ID입니다.

      • asset_idstring선택 사항

        동일 계정/키의 업로드 자산 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은 자동으로 재제출하지 않으며 reserved 요금은 여전히 대기 중일 수 있습니다.

    열거형
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atinteger필수

    Unix 초 단위 생성 시각입니다.

  • updated_atinteger필수

    Unix 초 단위 마지막 갱신 시각입니다.

  • reserved_quotainteger필수

    플랫폼 할당량 단위의 예약량이며 USD 금액이 아닙니다.

  • final_quotainteger필수

    플랫폼 할당량 단위의 최종 과금액이며 null은 아직 확정되지 않았음을 뜻합니다.

  • billing_statusstring필수

    예약/정산/환불 상태입니다. 작업 및 보관 상태와 별도로 확인하세요.

  • error_codestring선택 사항

    분기 로직에 사용할 수 있는 공개 오류 코드입니다.

  • error_messagestring선택 사항

    공개 오류 분류를 거친 사용자용 설명입니다.

  • resultsarray필수

    생성된 출력 항목이며 각 항목의 보관 상태는 독립적입니다.

    results 하위 필드(1)
    • []object선택 사항
      [] 하위 필드(7)
      • file_idstring선택 사항

        동일 계정/키의 관리형 파일 공개 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

키가 없거나 유효하지 않거나 만료 또는 폐기되었습니다.

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
개발할 준비가 되셨나요? 열기: 콘솔 API 키를 생성하거나 살펴보기: 기능.