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.
• For a task-oriented walkthrough, see the Image Generation guide.