> ## Documentation Index > Fetch the complete documentation index at: https://docs.dumplingai.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate AI Image > Generate an AI image using DumplingAI's image generation providers. ## Description This endpoint generates high-quality AI images using various models with different capabilities and price points. It supports multiple models with customizable parameters for each. ## Endpoint ``` POST https://app.dumplingai.com/api/v1/generate-ai-image ``` ## Headers * **Content-Type:** `application/json` * **Authorization:** Bearer `` (required) ## Request Body ```json theme={null} { "model": "string", // Required. The model to use for image generation "input": "object" // Required. Model-specific parameters } ``` ### Supported Models and Their Parameters #### FLUX.1-schnell (30 credits per image) ```json theme={null} { "model": "FLUX.1-schnell", "input": { "prompt": "string", // Required. Text prompt for image generation "seed": "number", // Optional. Random seed for reproducible generation "num_outputs": "number", // Optional. Number of images (1-4). Default: 1 "aspect_ratio": "string", // Optional. One of: "1:1", "16:9", "21:9", "3:2", "2:3", "4:5", "5:4", "3:4", "4:3", "9:16", "9:21". Default: "1:1" "output_format": "string", // Optional. One of: "webp", "jpg", "png". Default: "webp" "output_quality": "number", // Optional. 0-100. Default: 80 "num_inference_steps": "number", // Optional. 1-4. Default: 4 "disable_safety_checker": "boolean", // Optional. Default: false "go_fast": "boolean", // Optional. Default: true "megapixels": "string" // Optional. "1" or "0.25". Default: "1" } } ``` #### FLUX.1-dev (150 credits per image) ```json theme={null} { "model": "FLUX.1-dev", "input": { "prompt": "string", // Required. Text prompt for image generation "seed": "number", // Optional. Random seed for reproducible generation "image": "string", // Optional. Input image URL for image-to-image mode "prompt_strength": "number", // Optional. 0-1. Default: 0.8 "num_outputs": "number", // Optional. Number of images (1-4). Default: 1 "num_inference_steps": "number", // Optional. 1-50. Default: 28 "guidance": "number", // Optional. 0-10. Default: 3 "aspect_ratio": "string", // Optional. Same options as FLUX.1-schnell "output_format": "string", // Optional. Same options as FLUX.1-schnell "output_quality": "number", // Optional. 0-100. Default: 80 "disable_safety_checker": "boolean", // Optional. Default: false "go_fast": "boolean", // Optional. Default: true "megapixels": "string" // Optional. "1" or "0.25". Default: "1" } } ``` #### FLUX.1-pro and FLUX.1.1-pro (300 credits per image) ```json theme={null} { "model": "FLUX.1-pro", "input": { "prompt": "string", // Required. Text prompt for image generation "seed": "number", // Optional. Random seed for reproducible generation "steps": "number", // Optional. 1-50. Default: 25 "width": "number", // Optional. 256-1440. Must be multiple of 32 "height": "number", // Optional. 256-1440. Must be multiple of 32 "guidance": "number", // Optional. 2-5. Default: 3 "interval": "number", // Optional. 1-4. Default: 2 "aspect_ratio": "string", // Optional. One of: "custom", "1:1", "16:9", "2:3", "3:2", "4:5", "5:4", "9:16", "3:4", "4:3" "output_format": "string", // Optional. One of: "webp", "jpg", "png" "output_quality": "number", // Optional. 0-100. Default: 80 "safety_tolerance": "number", // Optional. 1-5. Default: 2 "prompt_upsampling": "boolean" // Optional. Default: false } } ``` #### FLUX.1-kontext-pro (200 credits per image) ```json theme={null} { "model": "FLUX.1-kontext-pro", "input": { "prompt": "string", // Required. Text description of what you want to generate, or instruction on how to edit the given image "input_image": "string", // Optional. Image URL to use as reference. Must be jpeg, png, gif, or webp "aspect_ratio": "string", // Optional. One of: "match_input_image", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "9:21", "2:1", "1:2". Default: "match_input_image" "seed": "number" // Optional. Random seed for reproducible generation } } ``` #### recraft-v3 (200 credits per image) ```json theme={null} { "model": "recraft-v3", "input": { "prompt": "string", // Required. Text prompt for image generation "size": "string", // Optional. One of the size options below. Default: "1024x1024" "style": "string" // Optional. One of the style options below. Default: "any" } } ``` Available size options: * "1024x1024" * "1365x1024" * "1024x1365" * "1536x1024" * "1024x1536" * "1820x1024" * "1024x1820" * "1024x2048" * "2048x1024" * "1434x1024" * "1024x1434" * "1024x1280" * "1280x1024" * "1024x1707" * "1707x1024" Available style options: * "any" * "realistic\_image" * "digital\_illustration" * "digital\_illustration/pixel\_art" * "digital\_illustration/hand\_drawn" * "digital\_illustration/grain" * "digital\_illustration/infantile\_sketch" * "digital\_illustration/2d\_art\_poster" * "digital\_illustration/handmade\_3d" * "digital\_illustration/hand\_drawn\_outline" * "digital\_illustration/engraving\_color" * "digital\_illustration/2d\_art\_poster\_2" * "realistic\_image/b\_and\_w" * "realistic\_image/hard\_flash" * "realistic\_image/hdr" * "realistic\_image/natural\_light" * "realistic\_image/studio\_portrait" * "realistic\_image/enterprise" * "realistic\_image/motion\_blur" ## Responses ### Success (200) Returns the generated image URLs and usage information. ```json theme={null} { "images": [ { "url": "string" // URL to the generated image } ], "prompt": "string", // The prompt used for generation "creditUsage": "number" // Total credits used for this request } ``` * **Content-Type:** application/json * **X-RateLimit-Limit:** The rate limit for the user. * **X-RateLimit-Remaining:** The remaining number of requests for the user. ### Bad Request (400) Returned if the request is invalid. ```json theme={null} { "error": "Error message describing the issue" } ``` ### Internal Server Error (500) Returned if there's an error during the image generation process. ```json theme={null} { "error": "Failed to generate image: [error message]" } ``` ## Example Requests ### Text-to-Image Generation ```bash theme={null} curl -X POST https://app.dumplingai.com/api/v1/generate-ai-image \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "FLUX.1-schnell", "input": { "prompt": "A serene landscape with mountains and a lake", "num_outputs": 1, "aspect_ratio": "16:9" } }' ``` ### Image Editing with FLUX.1-kontext-pro ```bash theme={null} curl -X POST https://app.dumplingai.com/api/v1/generate-ai-image \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "FLUX.1-kontext-pro", "input": { "prompt": "Change the background to a tropical beach while keeping the person in the exact same position", "input_image": "https://example.com/portrait.jpg", "aspect_ratio": "match_input_image" } }' ``` ## Notes * Credit costs per image vary by model: * FLUX.1-schnell: 30 credits * FLUX.1-dev: 150 credits * FLUX.1-pro: 300 credits * FLUX.1.1-pro: 500 credits * FLUX.1-kontext-pro: 200 credits * recraft-v3: 200 credits * Total credit usage is calculated as: model cost × number of images generated * Generated images are temporarily stored and accessible via the returned URLs * Safety checks are enabled by default to prevent NSFW content generation ## Rate Limiting Rate limit headers (`X-RateLimit-Limit` and `X-RateLimit-Remaining`) are included in the response to indicate the user's current rate limit status. ## OpenAPI ````yaml POST /api/v1/generate-ai-image openapi: 3.0.3 info: title: DumplingAI API version: 1.0.0 description: > REST API for DumplingAI's content intelligence and automation platform. All endpoints are grouped under `/api/v1`; most are secured via Bearer API keys unless an operation explicitly sets `security: []`. servers: - url: https://app.dumplingai.com description: Production security: - bearerAuth: [] tags: - name: YouTube description: Access metadata, search results, and transcripts from YouTube. - name: TikTok description: Retrieve TikTok profile, video, follower, and transcript data. - name: LinkedIn description: Programmatically fetch LinkedIn company and profile data. - name: Search description: Search-orientated endpoints spanning web, news, maps, and autocomplete. - name: Google description: Integrations with Google business listings and location data. - name: Scraping description: Webpage capture, crawling, and structured content extraction utilities. - name: Documents description: Document processing, conversion, and metadata utilities. - name: AI description: DumplingAI agent and knowledge base endpoints. - name: Developer Tools description: Utilities for executing sandboxed code via API. paths: /api/v1/generate-ai-image: post: tags: - AI summary: Generate AI image description: Generate an AI image using DumplingAI's image generation providers. operationId: generateAIImage requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerateAiImageRequest' examples: default: value: model: FLUX.1-schnell input: prompt: A dumpling-shaped rocket launching aspect_ratio: '16:9' responses: '200': description: Image generation task accepted. content: application/json: schema: $ref: '#/components/schemas/GenerateAiImageResponse' '400': description: Invalid request payload. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key. '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: GenerateAiImageRequest: type: object description: Parameters used to generate AI images through DumplingAI providers. required: - model - input properties: model: type: string description: Identifier of the image model to run. enum: - FLUX.1-schnell - FLUX.1-dev - FLUX.1-pro - FLUX.1.1-pro - FLUX.1-kontext-pro - recraft-v3 input: $ref: '#/components/schemas/AiImageInput' permanent: type: boolean description: When true, request permanent storage of generated assets. requestSource: $ref: '#/components/schemas/RequestSource' additionalProperties: false GenerateAiImageResponse: type: object required: - images - prompt - creditUsage - model properties: images: type: array items: type: object required: - url properties: url: type: string format: uri additionalProperties: false prompt: type: string creditUsage: type: integer model: type: string additionalProperties: false ErrorResponse: type: object properties: error: type: string description: Human-readable description of what went wrong. required: - error AiImageInput: type: object description: >- Model-specific parameters for AI image generation. Fields vary by selected model. required: - prompt properties: prompt: type: string description: Text description of the desired image. seed: type: integer description: Random seed to reproduce a previous generation. num_outputs: type: integer minimum: 1 maximum: 4 description: Number of images to generate. aspect_ratio: type: string description: Desired aspect ratio (e.g., `1:1`, `16:9`). output_format: type: string enum: - webp - jpg - png description: File format for generated images. output_quality: type: integer minimum: 0 maximum: 100 description: Quality level for lossy image formats. num_inference_steps: type: integer minimum: 1 description: Number of denoising steps to perform. guidance: type: number description: Guidance scale to balance creativity versus prompt adherence. prompt_strength: type: number minimum: 0 maximum: 1 description: Strength of the prompt when using image-to-image workflows. image: type: string format: uri description: Input image URL for image-to-image generation. input_image: type: string format: uri description: Reference image URL when using edit models. steps: type: integer description: Number of diffusion steps for certain models. width: type: integer description: Output width in pixels when using custom aspect ratios. height: type: integer description: Output height in pixels when using custom aspect ratios. interval: type: number description: Controls output variance for FLUX Pro models. disable_safety_checker: type: boolean description: Disable the upstream model safety checker where supported. go_fast: type: boolean description: Run the model in a speed-optimized configuration when available. megapixels: type: string description: Approximate megapixel target for the generated image. safety_tolerance: type: integer description: Safety threshold for filtering sensitive generations. prompt_upsampling: type: boolean description: Allow the provider to enhance the prompt for higher quality results. size: type: string description: >- Canvas dimensions for models that accept fixed sizes (e.g., `1024x1024`). style: type: string description: Artistic style preset for Recraft models. num_images: type: integer minimum: 1 description: Legacy field for number of images (maps to `num_outputs`). image_size: type: string description: >- Legacy field used by some automation templates to express aspect ratio. additionalProperties: true RequestSource: type: string description: Optional identifier describing where the API request originated. enum: - API - WEB - MAKE_DOT_COM - ZAPIER - N8N - PLAYGROUND - DEFAULT_AUTOMATION - AGENT_PREVIEW - AGENT_LIVE - AUTOPILOT - STUDIO securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key ````