Image Generation API

Generate an image and save it to the unified assets system in a single request.

POST /api/images/generate

The endpoint is guarded by an agent API key. AI agents call it with their organisation’s agent API key sent as the X-Agent-Api-Key header.

Request body

Field	Type	Required	Description
organizationId	string	Yes	Must match the agent API key’s organisation.
prompt	string	Yes	Image description.
fileName	string	Yes	Name for the saved file; include .jpg or .png.
jobId	string	One of jobId/requestId	Associates the asset with a job.
requestId	string	One of jobId/requestId	Alternative association identifier.
description	string	No	Description stored on the asset.
model	string	No	Defaults to fal-ai/nano-banana.
numImages	number	No	1–10, defaults to 1.
outputFormat	string	No	jpeg or png, defaults to jpeg.
aspectRatio	string	No	Defaults to 1:1.
metadata	object	No	Additional metadata stored on the asset.
createdByAgentType	string	No	Agent type for tracking; defaults to ai-agent.

Example request

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": "Detailed image description",
    "fileName": "my_image.jpg",
    "description": "Description for the asset",
    "aspectRatio": "16:9",
    "outputFormat": "jpeg",
    "createdByAgentType": "copywriter"
  }'

Response

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

Notes

• The response returns saved asset metadata (assets[] + generationInfo); it does not return image URLs or base64 content.
• Provide either jobId or requestId: one is required so the asset can be associated correctly.
• A platform-credit organisation can receive 402 Payment Required when its balance cannot cover the estimated request.
• An own-key organisation receives 422 Unprocessable Entity when its fal.ai key is missing. Runnit does not fall back to a platform key in this mode.
• For a task-oriented walkthrough, see the Image Generation guide.

When starting from an existing asset through the Assets API, you need source read access and upload permission on its collection. A refused request starts no generation job.

Saved-asset transformation returns 403 for private files, expense receipts and protected Finance files, including requests by their authorised reader. No job is created. Sources must be live images in a live collection; old files without a collection must be moved first. Queued work rechecks your live access and source identity before submitting it and saving output. A changed source or revoked access fails the job without saving a generated file. The same rules apply through call_public_api. The original file is unchanged.

This saved-asset restriction is separate from direct generation using a URL you supply. A supplied URL does not carry a saved file’s private access policy.