RunDiffusion Logo
Skip to content

Create generation

Run a generation job and get a request ID back immediately.

On this page

Generation is asynchronous. You submit a request, get a request_id back immediately, and then either poll Get run status or wait for a webhook.

POSThttps://api2.rundiffusion.com/api/v2/generate
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…
Idempotency-Keystringoptional
Repeating the same key from the same identity replays the original response instead of starting a second run. Send one on every create.Idempotency-Key: 6f4e2c8a-…

Query

team_idstringoptional
The team to bill. Omit it to bill your personal account. Part of the account selection rather than a filter, so it behaves identically on every endpoint. One team per request: a run lands on one account.https://api2.rundiffusion.com/api/v2/generate?team_id=Tq8vNc…

JSON body, or multipart/form-data when you are attaching files.

Body

tool_idstringRequired
The tool to run, from GET /api/v2/tools. Use the id exactly as returned.
tool_fields_hashstringRequired
Returned by GET /api/v2/tools/{tool_id} and passed back unchanged. It records which version of the tool schema you built these inputs from, so a run always states the schema it was built against. Any edit to the tool moves it, so read it from the detail response on each run rather than storing one. A mismatch returns 409 TOOL_SCHEMA_STALE with the live value in details.expected_tool_fields_hash: re-fetch the detail and rebuild.
inputsobjectoptional
Field values keyed by fieldKey, from the tool detail's fields[].fieldKey. Not by label, and not by slug. Value shape depends on the leaf's type: string for prompts, number for numeric fields, an option value for selects, an object for composite fields such as WIDTH_HEIGHT, or a reference descriptor for media. Read each leaf's display block for the values it will accept. Defaults to an empty object.
num_resultsintegeroptionaldefault 1
How many results to generate, from 1 to 64. Bounded further per tool by the num_results object on the tool detail; ignored when that object is null, which means the tool always returns exactly one.
webhook_urlstringoptional
An HTTPS URL to POST the terminal event to when the run reaches succeeded or failed. Strongly preferred over polling in production.
metadataobjectoptional
An arbitrary JSON object, up to 8 KB serialized, echoed back on status and webhook responses. Useful for correlating a run with a record in your own system.

Headers

Response

A successful create returns 202 Accepted, along with a Retry-After header that matches retry_after_seconds:

json
{
  "request_id": "9f8e7d6c-…",
  "status": "pending",
  "status_url": "https://api2.rundiffusion.com/api/v2/generate/9f8e7d6c-…",
  "retry_after_seconds": 8,
  "estimated_seconds": 12,
  "created": "2026-05-04T10:00:00Z"
}

The run has been accepted, not completed. Wait retry_after_seconds before the first poll, then follow status_url.

request_idstring
The handle for this run, a UUID rather than the 20-character IDs used for tools, uploads, and library runs. Use it to poll status and to match a webhook to its run.
statusstring
Always pending on create. It advances as the run progresses.
status_urlstring
The fully qualified URL to poll. Follow it rather than assembling one.
retry_after_secondsinteger
How long to wait before the first poll. It matches the Retry-After header. Polling sooner wastes a request and counts against your rate limit.
estimated_secondsinteger | null
The tool's average generation time, for setting expectations in a UI. Null for a newly added tool with no history yet.
createdstring (ISO 8601)
When it was created, in UTC.

Sending files

When an input needs raw bytes rather than a value or a reference, send the request as multipart/form-data instead of JSON.

Include a payload part holding the same JSON body you would otherwise send, plus one or more files parts. Reference each file from inputs by its index:

json
{
  "kind": "MULTIPART",
  "file_index": 0
}

If a file already exists in RunDiffusion, reference it from inputs with an UPLOAD_REF or LIBRARY_REF descriptor instead and keep the request as plain JSON.

An upload takes the id from Create an upload:

json
{ "kind": "UPLOAD_REF", "id": "Yb3kQ9…" }

A past generation takes the id from List generations, whole. There is nothing to split:

json
{ "kind": "LIBRARY_REF", "id": "Kp7mZq…:3f2a9c14-…" }

Limits

LimitValue
Input files per request12
Size per file50 MB
Total multipart request size250 MB
Serialized metadata8 KB
Concurrent active runs per identity10

The file count includes multipart files and UPLOAD_REF / LIBRARY_REF references combined. Exceeding it returns TOO_MANY_INPUT_FILES, an oversized file returns UPLOAD_TOO_LARGE, and too many simultaneous runs returns ACTIVE_RUN_CAP.

Errors

CodeWhat to do
TOOL_SCHEMA_STALEReturns 409 with details.expected_tool_fields_hash. Re-fetch the tool and rebuild the request with the new hash.
INSUFFICIENT_BALANCEThe account is out of tokens. Surface this rather than retrying.
ACTIVE_RUN_CAPToo many runs in flight. Wait for one to finish.
NUM_RESULTS_LIMITnum_results exceeds what the account or tool permits.
CONTENT_POLICY_VIOLATIONThe request was blocked. Do not retry unchanged.
IDEMPOTENCY_KEY_CONFLICTThe key was reused with a different body. Use a fresh key.
RATE_LIMITED10 creates per minute and 100 per hour, both enforced. See Rate limits.

The full list is in Errors.

View as Markdown