RunDiffusion Logo
Skip to content

Preview cost

Find out what a run would cost, and whether it would be allowed, without starting it.

On this page

Takes the same body as Create generation and reports what it would cost without starting anything. Handling a block here is considerably cheaper than a failed generation.

POSThttps://api2.rundiffusion.com/api/v2/generate/preview-cost
AcceptsOAuth device flowPersonal API Access TokenCompany API Access Token

Request

Headers

AuthorizationstringRequired
Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See Authentication.Authorization: Bearer eyJhbGciOi…

Takes the same body as generate and tells you what the run would cost without starting it. This endpoint is JSON only, so it does not accept file parts.

Response

200 OK, whether or not the run would be allowed.

json
{
  "can_run": true,
  "blocking_reason": null,
  "tokens_per_result": 85,
  "total_tokens": 170,
  "free_tokens_per_result": 0,
  "estimated_seconds": 12
}

total_tokens is tokens_per_result multiplied by num_results, less anything covered by free_tokens_per_result. All three are whole tokens.

A blocked run returns 200 as well, with the reason attached:

json
{
  "can_run": false,
  "blocking_reason": "Your balance of (12) is too low to run this tool",
  "tokens_per_result": 85,
  "total_tokens": 170,
  "free_tokens_per_result": 0,
  "estimated_seconds": 12
}

Check can_run before submitting. Handling a block here is considerably cheaper than a failed generation.

can_runboolean
Whether generate would accept this exact body. This is the field to branch on, and the only one whose meaning is stable.
blocking_reasonstring | null
Human-readable explanation when can_run is false, and null otherwise. For display only, never for branching.
tokens_per_resultinteger
Authoritative cost for one result on this account, in whole tokens. This can differ from the list price on the tool.
total_tokensinteger
tokens_per_result multiplied by num_results, less anything covered by free_tokens_per_result. This is what the run will actually deduct.
free_tokens_per_resultinteger
Per-result tokens covered by the account's free allowance, already subtracted from total_tokens. Zero when no allowance applies.
estimated_secondsinteger
The tool's average generation time per result, for setting expectations.

Errors

CodeWhat to do
TOOL_NOT_FOUNDReturns 404. No such tool, or not one this credential can see.
TOOL_SCHEMA_STALEReturns 409 with details.expected_tool_fields_hash. Re-fetch the tool and rebuild the request with the new hash.
TOOL_NOT_RUNNABLE_V1Returns 400. The tool uses a field type this API cannot run yet.
INVALID_REQUESTReturns 400. A missing or malformed field in the body.
RATE_LIMITEDReturns 429. See Rate limits. See Rate limits.

The full list is in Errors.

View as Markdown