Image Generation

Images are a creation primitive in Naive API v2. Two tools cover what an agent typically needs: AI image generation for original visuals (FLUX, Stable Diffusion, Recraft), and stock photo search for free, license-clean photography. Both are identity-aware and billing-integrated.

CLI First

# Generate images and wait for result
naive images generate --model fal-ai/flux/schnell "A minimalist illustration of an AI robot working at a desk" --num-images 2 --wait

# Search stock photos
naive images stock "modern office workspace" --count 10

Tools

Tool	Type	Description	Cost
`generate_images`	Core	Generate images from a text prompt (async)	Dynamic (model-dependent)
`stock_search`	Core	Search free stock photos	Free
`image_models`	Core	List all available image generation models with parameters	Free
`image_status`	Core	Check status of an image generation job	Free

Generating Images

The generate_images tool submits an async image generation job. The input object supports any model-specific parameters.

curl -X POST https://api.usenaive.ai/v1/images/generate \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fal-ai/flux/schnell",
    "input": {
      "prompt": "A minimalist illustration of an AI robot working at a desk, flat design, blue and white",
      "image_size": "square_hd",
      "num_images": 2,
      "seed": 42
    }
  }'

const response = await fetch("https://api.usenaive.ai/v1/images/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nv_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "fal-ai/flux/schnell",
    input: {
      prompt: "A minimalist illustration of an AI robot working at a desk, flat design, blue and white",
      image_size: "square_hd",
      num_images: 2,
      seed: 42,
    },
  }),
});
const job = await response.json();

Response (202):

{
  "job_id": "job-uuid",
  "status": "queued",
  "type": "image_generation",
  "model": "fal-ai/flux/schnell",
  "estimated_credits": 1.2,
  "hint": "Poll GET /v1/jobs/job-uuid or GET /v1/images/job-uuid. Credits charged on completion only."
}

Parameters (Common)

Param	Type	Required	Default	Description
`prompt`	string	Yes	—	Text description of the image
`image_size`	string	No	`square_hd`	`square_hd`, `landscape_4_3`, `landscape_16_9`, `portrait_4_3`, `portrait_16_9`
`num_images`	number	No	1	Number of images (1-4)
`seed`	number	No	Random	Reproducibility seed
`guidance_scale`	number	No	3.5	CFG guidance (FLUX Schnell/Dev only)
`num_inference_steps`	number	No	4	Quality steps (FLUX Schnell: 1-12)
`output_format`	string	No	`jpeg`	`"jpeg"` or `"png"`

FLUX Pro v1.1 does NOT support guidance_scale or num_inference_steps. Use FLUX Schnell or Dev if you need these.

Checking Status

Poll until the job completes:

curl https://api.usenaive.ai/v1/images/job-uuid \
  -H "Authorization: Bearer nv_sk_your_key"

Response (completed):

{
  "status": "completed",
  "result": {
    "images": [
      { "url": "https://fal.media/files/.../img1.png", "width": 1024, "height": 1024 },
      { "url": "https://fal.media/files/.../img2.png", "width": 1024, "height": 1024 }
    ],
    "seed": 42
  },
  "credits_used": 1.2
}

Cost

Image generation pricing is dynamic — based on the model’s per-unit cost, converted to credits at $0.05/credit. Preview costs before submitting:

curl "https://api.usenaive.ai/v1/images/pricing?model=fal-ai/flux/schnell&num_images=2" \
  -H "Authorization: Bearer nv_sk_your_key"

{
  "model": "fal-ai/flux/schnell",
  "estimated_credits": 1.2,
  "unit_price_usd": 0.02,
  "credit_value_usd": 0.05
}

Available Models

Use GET /v1/images/models to see the full dynamically-fetched list. Common models:

Model	Mode	Best For
`fal-ai/flux/schnell`	text-to-image	Fast generation (~5s), good default
`fal-ai/flux-pro/v1.1`	text-to-image	Highest quality (~15s)
`fal-ai/flux/dev`	text-to-image	Experimental, supports guidance
`fal-ai/flux-realism`	text-to-image	Photorealistic results
`fal-ai/recraft-v3`	text-to-image	Design-focused (logos, illustrations)
`fal-ai/stable-diffusion-v35-large`	text-to-image	Classic SD with negative prompts

Stock Photo Search

Search free stock photos — no credits charged, no generation wait.

curl "https://api.usenaive.ai/v1/images/stock?query=team+collaboration&count=5&orientation=landscape" \
  -H "Authorization: Bearer nv_sk_your_key"

const response = await fetch(
  "https://api.usenaive.ai/v1/images/stock?query=team+collaboration&count=5&orientation=landscape",
  { headers: { "Authorization": "Bearer nv_sk_your_key" } }
);
const { photos } = await response.json();

Response:

{
  "photos": [
    {
      "id": 3184339,
      "url": "https://stock.example.com/photo/3184339",
      "src": { "original": "https://images.example.com/...", "large": "...", "medium": "..." },
      "alt": "Team meeting in modern office",
      "width": 1920,
      "height": 1080,
      "photographer": "Kampus Production"
    }
  ]
}

Parameters

Param	Type	Required	Default	Description
`query`	string	Yes	—	Search keywords
`count`	number	No	10	Results count (1-80)
`orientation`	string	No	—	`landscape`, `portrait`, or `square`
`color`	string	No	—	Filter by dominant color
`size`	string	No	—	Minimum size: `large`, `medium`, `small`

Prompt Tips

Marketing Assets
Social Media
Logos & Icons

A professional product mockup of a SaaS dashboard on a laptop,
clean UI with charts, soft gradient background in blue and purple,
photorealistic, high detail

Minimal app icon for a note-taking app, single pencil glyph on solid
indigo background, rounded square, flat design, no text, white bg

For logos, always specify “no text” and “white background”. Text in AI-generated images is often garbled. Add text separately.

Error Handling

Error	Cause	Recovery
`insufficient_credits`	Not enough credits for generation	Preview cost with `/v1/images/pricing`, then top up
`provider_error`	AI model provider rejected the request	Check model parameters against `/v1/images/models`
`invalid_model`	Model ID not recognized	Use `GET /v1/images/models` for valid IDs

When to Use Each

Need	Tool	Why
Custom branded visuals	`generate_images`	Unique content matching your brand
Logo or icon concepts	`generate_images`	No stock option for custom marks
Generic backgrounds	`stock_search`	Fast, free, high quality
Social media photos	`stock_search`	Professional, free, immediate

Typical Workflow

Agent receives task: "Create social media graphics for the product launch"
    │
    ├─ POST /v1/images/generate                → Generate custom hero image
    │   { model: "fal-ai/flux-pro/v1.1",
    │     input: { prompt: "Product launch banner...", num_images: 4 } }
    │   → job_id: job-uuid-1
    │
    ├─ GET /v1/jobs/job-uuid-1                 → Poll until complete
    │   → 4 images generated with URLs
    │
    ├─ GET /v1/images/stock?query=celebration  → Find supporting stock photos
    │   → 10 free stock photos
    │
    └─ POST /v1/email/send                     → Send to team for review
        { body: "Here are the launch graphics..." }

​CLI First

​Tools

​Generating Images

​Parameters (Common)

​Checking Status

​Cost

​Available Models

​Stock Photo Search

​Parameters

​Prompt Tips

​Error Handling

​When to Use Each

​Typical Workflow

CLI First

Tools

Generating Images

Parameters (Common)

Checking Status

Cost

Available Models

Stock Photo Search

Parameters

Prompt Tips

Error Handling

When to Use Each

Typical Workflow