Image Generation

Runnit image generation is a single-call, auto-save operation. One request generates an image, downloads it server-side, and saves it straight into your asset library: you never handle binary data or base64 payloads.

How it works

When you call the image-generation endpoint, Runnit:

Generates the image (default model fal-ai/nano-banana).
Downloads the result server-side.
Saves it into the unified assets system.
Returns a lightweight success response with the saved asset metadata.

This collapses what used to be a three-step workflow (generate → download → save) into one request, which keeps token usage low for AI agents.

Requesting an image

Send a POST to /api/images/generate with at least a prompt, a file name, and either a jobId or a requestId:

curl -X POST https://api.runnit.io/api/images/generate \
  -H "Content-Type: application/json" \
  -H "X-Agent-Api-Key: <your-agent-api-key>" \
  -d '{
    "organizationId": "your-org-id",
    "jobId": "your-job-id",
    "prompt": "A beautiful sunset over mountains",
    "fileName": "sunset.jpg",
    "description": "Hero image for the launch campaign",
    "aspectRatio": "16:9",
    "outputFormat": "jpeg"
  }'

Common parameters

Field	Required	Notes
`prompt`	Yes	Description of the image to generate.
`fileName`	Yes	Saved file name; include `.jpg` or `.png`.
`jobId` or `requestId`	One required	Associates the asset with a job.
`organizationId`	Yes	Must match your agent API key’s organisation.
`numImages`	No	1–10, defaults to 1.
`aspectRatio`	No	Defaults to `1:1`.
`outputFormat`	No	`jpeg` or `png`, defaults to `jpeg`.
`description`	No	Stored on the asset; recommended for organisation.

Response

{
  "success": true,
  "message": "Images generated and saved successfully",
  "assets": [
    {
      "id": "asset-uuid",
      "fileName": "sunset.jpg",
      "fileType": "image",
      "mimeType": "image/jpeg",
      "fileSize": 125432,
      "createdAt": "2025-10-08T12:00:00Z"
    }
  ],
  "generationInfo": {
    "model": "fal-ai/nano-banana",
    "prompt": "A beautiful sunset over mountains",
    "aspectRatio": "16:9",
    "outputFormat": "jpeg"
  }
}

The saved image is immediately viewable in the app under the associated job’s assets.