AI Image API¶

Generate images using multiple AI providers: DALL-E, Stable Diffusion, and Flux Pro.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /aiimage

Endpoints¶

Check Availability¶

GET /aiimage/check-availability

Check if image generation is available (uses a 10-second lock to prevent concurrent generation).

Response (available):

{ "status": "success", "message": "Image generation is available." }

Response (busy — 409):

{ "status": "error", "message": "Image generation in progress. Please try again later." }

Get Available Engines¶

GET /aiimage/versions

Returns the currently configured image generation engines and their versions.

Response:

{
  "dall-e": "dalle3",
  "stable-diffusion": "sd3-large"
}

Generate Image¶

POST /aiimage/generate-image

The request parameters vary by engine. Set image_generator to select the engine.

Common Parameters¶

Parameter	Type	Required	Description
`image_generator`	string	Yes	Engine: `dall-e`, `stablediffusion`, `flux-pro`, `ideogram`, `flux-pro-kontext`
`image_number_of_images`	integer	Yes	Number of images to generate

DALL-E Parameters¶

Parameter	Type	Required	Description
`description`	string	Yes	Image prompt
`size`	string	Yes	`256x256`, `512x512`, `1024x1024`, `1792x1024`, `1024x1792`
`quality`	string	Yes	`standard` or `hd`
`image_style`	string	No	Style modifier (e.g., `vivid`)
`image_lighting`	string	No	Lighting modifier
`mood`	string	No	Mood modifier

Stable Diffusion Parameters¶

Parameter	Type	Required	Description
`stable_description`	string	Yes	Image prompt
`type`	string	Yes	`text-to-image`, `image-to-image`, `upscale`, `multi-prompt`
`image_resolution`	string	Yes	Resolution as `WIDTHxHEIGHT` (e.g., `512x512`)
`negative_prompt`	string	No	What to exclude from the image
`style_preset`	string	No	Style preset name
`image_src`	file	Conditional	Required for `image-to-image` and `upscale`

Flux Pro Parameters¶

Parameter	Type	Required	Description
`description_flux_pro`	string	Yes	Image prompt

curl

curl -X POST https://api.vell.ai/api/v1/aiimage/generate-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_generator": "dall-e",
    "description": "A futuristic cloud data center floating in space",
    "size": "1024x1024",
    "quality": "hd",
    "image_number_of_images": 1
  }'

Response:

{
  "status": "success",
  "images": [
    {
      "id": 123,
      "title": "cloud-data-center.png",
      "input": "A futuristic cloud data center floating in space",
      "output": "uploads/cloud-data-center.png"
    }
  ],
  "image_storage": "public"
}

Credit cost: 1 credit per image generated.

Error Responses:

Status	Description
409	Generation already in progress (locked)
419	Insufficient credits
429	Daily image limit exceeded

Get Recent Images¶

GET /aiimage/recent-images

Returns the 10 most recently generated images for the authenticated user.

Response:

[
  {
    "id": 123,
    "title": "cloud-data-center.png",
    "input": "A futuristic cloud data center...",
    "output": "uploads/cloud-data-center.png",
    "created_at": "2026-02-26T10:00:00Z"
  }
]

Use Cases¶

Generate Product Imagery¶

Check availability with GET /aiimage/check-availability
Generate with DALL-E using hd quality and 1024x1024 size
Retrieve the image URL from the output field
Use in your marketplace listing or marketing materials

Batch Image Generation with Different Engines¶

Generate a hero image with DALL-E (dall-e, hd quality)
Create variations with Stable Diffusion (stablediffusion, image-to-image)
Generate social media crops at different sizes using image_resolution

Image-to-Image Enhancement¶

Upload a source image via image_src (multipart form)
Set type: "image-to-image" with image_generator: "stablediffusion"
Provide a stable_description to guide the transformation
Or use type: "upscale" to enhance resolution