Generations

Estimate credits

Validate model input and preview the current account credit estimate before creating a task.

Endpoint

POST/api/v1/developer/generations/estimate

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Scope: generations:write

Replace the example model_key and parameters with values from the current catalog. Unknown fields and provider/URL/storage/endpoint injection are rejected.

No Idempotency-Key is required. Review the estimate before creating with the same input; an estimate is not a fixed price guarantee.

Request parameters

Field	Type	Required	Description
`model_key`	string	Yes	Exact key from the current public model catalog.
`operation`	string	Yes	image_generation or video_generation; must be supported by the selected model.
`prompt`	string	Yes	Nonempty prompt, at most 8,000 characters.
`negative_prompt`	string	No	At most 8,000 characters, subject to model support.
`parameters`	object	No	Only parameters accepted by this model's input_schema; include required size/duration settings where applicable.
`reference_upload_ids`	UUID[]	No	Completed upload_id values, at most 8; model-specific limits may be lower.
`client_trace_id`	string	No	At most 128 characters matching [A-Za-z0-9._:-]+.

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/generations/estimate' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>' \
  --header 'Content-Type: application/json' \
  --data '{"model_key":"<model_key_from_catalog>","operation":"image_generation","prompt":"A bright editorial product still life","parameters":{}}'

Response HTTP 200

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`model_key / operation`	string	Yes	Validated model and operation.
`estimated_credits`	integer	Yes	Current estimate for this input and account.
`currency`	string	Yes	Account currency configuration; anonymous quota is omitted.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "model_key": "<model_key_from_catalog>",
    "operation": "image_generation",
    "estimated_credits": 10,
    "currency": "USD"
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT
422 — FIELD_REQUIRED / FIELD_INVALID
402 — CREDITS_INSUFFICIENT

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}