AI Primary

Generate an image based on a prompt with idempotency key

POST /images/generate-with-idempotency
Bearer auth

Creates an image using an AI model based on the provided prompt and parameters.

Headers

  • idempotency-key string

    A unique key to ensure idempotent requests.

application/json

Body Required

Parameters for the image generation

  • prompt string Required

    The text prompt to generate the image from.

  • aspectRatio string

    The aspect ratio of the generated image.

    Default value is 1:1.

  • artStyle string

    the

  • artDescription string
  • themeStyle string
  • themeDescription string
  • model string

    AI model

  • provider string

    provider of AI model

Responses

  • 200 application/json

    Image generated successfully

    Hide response attributes Show response attributes object
    • success boolean
    • code integer(int32)
    • message string
    • data object
      Hide data attributes Show data attributes object
      • url string | null

        The URI of the generated image.

      • mimeType string

        The MIME type of the generated image.

      • prompt string

        The prompt used to generate the image.

      • created string(date-time)

        The timestamp when the image was created.
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • success boolean
    • code integer
    • errorCode string
    • message string
    • timestamp string(date-time)
  • 429 application/json

    Too Many Requests

    Hide response attributes Show response attributes object
    • success boolean
    • code integer
    • errorCode string
    • message string
    • timestamp string(date-time)
  • 500 application/json

    Internal Server Error - Failed to generate image

    Hide response attributes Show response attributes object
    • success boolean
    • code integer
    • errorCode string
    • message string
    • timestamp string(date-time)
POST /images/generate-with-idempotency 
curl \
 --request POST 'https://api.huy-devops.site/api/images/generate-with-idempotency' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "idempotency-key: string" \
 --data '{"prompt":"A beautiful sunset over a mountain landscape","aspectRatio":"16:9","artStyle":"cartoon","artDescription":"something","themeStyle":"something","themeDescription":"something","model":"gpt-4o","provider":"openai"}'
Request examples 
# Headers
idempotency-key: string

# Payload
{
  "prompt": "A beautiful sunset over a mountain landscape",
  "aspectRatio": "16:9",
  "artStyle": "cartoon",
  "artDescription": "something",
  "themeStyle": "something",
  "themeDescription": "something",
  "model": "gpt-4o",
  "provider": "openai"
}
Response examples (200) 
{
  "success": true,
  "code": 200,
  "message": "string",
  "data": {
    "url": "string",
    "mimeType": "image/png",
    "prompt": "A beautiful sunset over a mountain landscape",
    "created": "2025-09-01T12:00:00Z"
  }
}
Response examples (400) 
{
  "success": false,
  "code": 400,
  "errorCode": "INVALID_IMAGE_PROMPT",
  "message": "Invalid prompt or parameters for image generation",
  "timestamp": "2025-05-04T09:42:00Z"
}
Response examples (429) 
{
  "success": false,
  "code": 429,
  "errorCode": "IMAGE_GENERATION_QUOTA_EXCEEDED",
  "message": "Image generation quota has been exceeded",
  "timestamp": "2025-05-04T09:42:00Z"
}
Response examples (500) 
{
  "success": false,
  "code": 500,
  "errorCode": "GENERATION_ERROR",
  "message": "An error occurred during content generation",
  "timestamp": "2025-05-04T09:42:00Z"
}