---
title: "Submit Image Generation Job"
method: POST
path: "/v1/capabilities/image.generate.v1/jobs"
tags: ["public_api", "external"]
---

# Submit Image Generation Job

`POST /v1/capabilities/image.generate.v1/jobs`

## Request

- Base URL: `https://api.hydracept.com`
- URL: `https://api.hydracept.com/v1/capabilities/image.generate.v1/jobs`
- Auth: HTTP bearer

Submit an image generation job using the quoted model and billing mode from the request.

## Request body

- CapabilityJobRequest
  - `externalRef` string, nullable: Opaque caller-owned correlation reference. Never sent to providers. Max 255 characters.
  - `tags` string[]: Caller-owned flat labels for correlation and future exact-match filtering. At most 32 tags; each tag max 256 characters.
  - `metadata` object: Opaque caller-owned JSON bookkeeping. Never interpreted or sent to providers. Serialized size capped at 16384 UTF-8 bytes.
  - `responseSchema` object, nullable
  - `toolSchemas` object[], nullable
  - `sampling` HydraceptSampling: Optional product-requested sampling. Providers that reject custom sampling omit these.
    - `temperature` number, nullable
    - `reasoningIntent` 'omit' | 'economy' | 'balanced' | 'deep' | 'maximum'
  - `readerDelivery` ReaderDelivery: Opt in to partial text output on a durable text job. ``boundary`` is ``paragraph``: events close on a blank line, or on a sentence-sized span once the hold limit is reached. Tokens are not events.
    - `boundary` 'paragraph'
  - `maturityRating` 'G' | 'PG' | 'PG13' | 'R' | 'NC17'
  - `matureContentTraits` MatureContentTrait[]
  - `maturitySource` 'explicit_invocation' | 'project_default' | 'workload_derived' | 'legacy_default'
  - `context` CapabilityContext
    - `productId` string
    - `environment` string
    - `projectId` string, nullable
    - `dataClassification` 'Public' | 'Internal' | 'Confidential' | 'PrivateUserContent' | 'Manuscript'
    - `retentionRequirement` 'HashesOnly' | 'Transient' | 'EncryptedShortTerm' | 'ProductManaged' | 'ProductionAsset'
  - `input` object
  - `inputPayloadRef` string, nullable: Verified payload id from POST /v1/payloads. When set, inline input is optional; the server resolves content before admission, estimate, and stream dispatch.
  - `execution` CapabilityExecutionOptions
    - `executionPreference` string
    - `billingMode` string, nullable
    - `credentialSource` string, nullable
    - `quoteId` string, nullable
    - `estimateId` string, nullable: Inbound alias of quoteId. Prefer quoteId and pricing.quote.
    - `maximumCharge` object, nullable
    - `executionConstraints` ExecutionConstraints
      - `maxCostUsd` number, nullable
      - `providerPin` string, nullable
      - `preferredModel` string, nullable
      - `autoSelect` boolean: Opt in to smart fallback when preferredModel is physically unavailable. Ignored when preferredModel is omitted.
      - `budgetEnforcement` string, nullable: warn (admit over ceiling) or prevent (HTTP 402). Setting maxCostUsd without this is prevent.
      - `maxDurationSeconds` integer, nullable: Provider execution deadline in seconds after the job starts running. Does not include queue wait. timeoutSeconds is accepted as an alias.
  - `idempotencyKey` string
  - `correlationId` string, nullable
  - `taskKind` string, nullable
  - `pin` ExactTargetPin: Exact execution target. Hydracept does not substitute.
    - `target` string, required

## Response `200`

Successful response

- HydraceptJob
  - `jobId` string, required
  - `capabilityKey` string, required
  - `status` 'queued' | 'running' | 'awaiting_approval' | 'succeeded' | 'failed' | 'canceling' | 'canceled' | 'needs_attention', required
  - `projectId` string, nullable
  - `productId` string, nullable
  - `externalRef` string, nullable
  - `tags` string[]
  - `metadata` object
  - `createdAt` string, date-time, nullable
  - `completedAt` string, date-time, nullable
  - `estimatedCost` number, nullable
  - `actualCost` number, nullable: Provider cost when the receipt has evidence for it; null when unknown. Never the customer charge (that is pricing.charge.customerCharge) and never a fabricated 0.
  - `pricing` HydraceptReceiptPricing: Canonical pricing on a receipt. Legacy micros fields remain for compatibility.
    - `quote` ReceiptQuote
      - `quoteId` string, nullable
      - `kind` 'fixed' | 'estimate' | 'range'
      - `chargeBasis` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `serviceFee` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `customerTotal` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `maximumCustomerTotal` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `expiresAt` string, date-time, nullable
      - `pricingInputsHash` string, nullable
    - `charge` ReceiptCharge
      - `customerCharge` Money, required: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `customerDebit` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `chargedAt` string, date-time, nullable
    - `providerUsage` ReceiptProviderUsage
      - `reportedCost` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `costBearer` 'hydracept' | 'customer' | 'none' | 'unknown'
    - `providerCost` ReceiptProviderCost: Provider cost evidence. ``amount`` is null when unknown — never ``0``. ``basis``/``status`` explain how the amount was obtained; a usage-priced cost names the pinned ``priceScheduleId`` so a later catalog change cannot silently rewrite historical provider cost.
      - `amount` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `status` string
      - `basis` string
      - `priceScheduleId` string, nullable
    - `policy` ReceiptPricingPolicy
      - `serviceFeeBps` integer
      - `pricingMode` 'byok' | 'managed', required
    - `presentation` PresentationMoney: Optional converted display of a charge. Not part of the financial receipt.
      - `convertedTotal` Money, required: Hydracept price before transactional tax. ``amountMicros`` is authority.
        - `amountMicros` integer, required
        - `currency` string, required
        - `amountMinor` integer, required
        - `display` string, required
      - `fx` ScaledFxRate, required: FX snapshot using scaled integers — never IEEE binary floats.
        - `rateScaled` integer, required
        - `scale` integer
        - `baseCurrency` string, required
        - `quoteCurrency` string, required
        - `source` string, nullable
        - `asOf` string, nullable
    - `mode` 'byok' | 'managed'
    - `estimatedProviderPriceBasisMicros` integer, nullable
    - `observedUsage` object, nullable
    - `hydraceptInferenceFeeMicros` integer
    - `providerReportedCostMicros` integer, nullable
    - `customerCharge` CustomerCharge
      - `upstreamMicros` integer, required
      - `hydraceptFeeMicros` integer, required
      - `customerTotalMicros` integer, required
      - `currency` string
      - `lineItems` PricingLineItem[]
        - `label` string, required
        - `upstreamMicros` integer, required
        - `hydraceptFeeMicros` integer
        - `includedProcessing` boolean
    - `hydracept` HydraceptReceiptHydracept
      - `serviceFeeRateBps` integer
      - `inferenceFeeMicros` integer
    - `executionPlanId` string, nullable
    - `pricingSnapshotIds` string[]
    - `quoteId` string, nullable
    - `estimateId` string, nullable: Inbound/outbound alias of quoteId. Prefer quoteId and pricing.quote.
    - `pricingVersion` string, nullable
    - `pricingInputFingerprint` string, nullable
    - `resolvedRoute` object, nullable
    - `estimatedCharge` object, nullable
    - `maximumAuthorizedCharge` object, nullable
    - `actualCharge` object, nullable
    - `price` Money: Hydracept price before transactional tax. ``amountMicros`` is authority.
      - `amountMicros` integer, required
      - `currency` string, required
      - `amountMinor` integer, required
      - `display` string, required
    - `basisEstimated` object, nullable
    - `basisActual` object, nullable
    - `fundingSource` string, nullable
    - `trialCoveredMicros` integer, nullable
    - `customerDebitedMicros` integer, nullable
    - `actualChargeMicros` integer, nullable
  - `currency` string
  - `artifacts` HydraceptJobArtifactRef[]
    - `artifactId` string, required
    - `mediaType` string, required
    - `kind` string, required
    - `downloadPath` string, nullable
    - `sha256` string, nullable
    - `exportSha256` string, nullable: SHA-256 of default export bytes (neutral generator metadata) when they differ from sha256.
    - `byteLength` integer, nullable
    - `variantIndex` integer, nullable
    - `slotStatus` string, nullable
    - `selected` boolean, nullable
    - `label` string, nullable
    - `filename` string, nullable
    - `sliceCellId` string, nullable
  - `variantSet` HydraceptVariantSet
    - `schemaVersion` string
    - `requestedCount` integer, required
    - `completedCount` integer, required
    - `failedCount` integer, required
    - `selectedArtifactId` string, nullable
  - `receiptId` string, nullable
  - `primaryArtifactId` string, nullable
  - `typedOutput` unknown
  - `warnings` object[]
  - `error` object, nullable
  - `progress` HydraceptJobProgress: Where a durable job has reached, as reported by the activity that owns the work. ``updatedAt`` is required whenever progress is present, so a reader can always tell how fresh the projection is. ``percent`` and ``etaSeconds`` are optional on purpose: they are present only when the authority (a provider that reports them) can compute them. Unknown values are omitted rather than defaulted to ``0``.
    - `phase` string, required
    - `step` string, required
    - `percent` number, nullable
    - `etaSeconds` integer, nullable
    - `updatedAt` string, date-time, required
  - `diagnostics` HydraceptJobDiagnostics
    - `backendKind` string, required
    - `backendState` string, required
    - `backendId` string, required
  - `requestSnapshot` object, nullable: Canonical submitted request for rerunning the same inputs in Studio (not the sealed receipt).
  - `nextAction` string, nullable
  - `pollAfterSeconds` integer, nullable
  - `retry` object, nullable
  - `approval` object, nullable: Sanitized human-gate payload. Present only while the job awaits approval.

## Other responses

- `401`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `402`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `403`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `409`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `422`: Validation failure: public envelope plus Pydantic `detail` / `validationErrors`
- `429`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `500`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `502`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `503`: Structured public error envelope (`code`, `message`, `requestId`, …)

---

[API](https://skmtc.dev/hydracept/apis/hydracept-public-api.md) · [All operations](https://skmtc.dev/hydracept/apis/hydracept-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hydracept/apis/hydracept-public-api/revisions/2d41a8069ede?raw)