---
title: "Preview variant packing plan"
method: POST
path: "/v1/capabilities/image.generate.v1/plan"
tags: ["public_api", "external", "capabilities"]
---

# Preview variant packing plan

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

## Request

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

## 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

- object

## Other responses

- `401`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `403`: 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)