> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate images

> Submits an image generation. Reference inputs such as `reference_images` take asset ids from `POST /v1/uploads` or an earlier output. Returns immediately with `status: pending`; credits are reserved now and settled when the job finishes. Poll `GET /v1/generations/{id}` until `completed` or `failed`.



## OpenAPI

````yaml /openapi.v1.json post /v1/images
openapi: 3.1.0
info:
  contact:
    email: hello@ekly.ai
    name: Ekly
    url: https://docs.ekly.ai
  description: >-
    Generate images, video, music and speech with the same models and credits as
    the Ekly app.


    Authenticate with an organization API key from Settings → Team as a bearer
    token. Every endpoint lives under /v1 and follows the additive-only
    versioning policy at https://docs.ekly.ai/versioning.
  termsOfService: https://ekly.ai/terms
  title: Ekly API
  version: '1.0'
servers:
  - description: Production
    url: https://api.ekly.ai
security:
  - ApiKey: []
tags:
  - description: Public, versioned developer API
    name: v1
paths:
  /v1/images:
    post:
      tags:
        - v1
      summary: Generate images
      description: >-
        Submits an image generation. Reference inputs such as `reference_images`
        take asset ids from `POST /v1/uploads` or an earlier output. Returns
        immediately with `status: pending`; credits are reserved now and settled
        when the job finishes. Poll `GET /v1/generations/{id}` until `completed`
        or `failed`.
      operationId: create_image
      parameters:
        - description: >-
            Reuse the same value when retrying the same request; a repeat
            returns the original generation without charging again. Reusing it
            with a different body returns 409.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - maxLength: 128
                type: string
              - type: 'null'
            description: >-
              Reuse the same value when retrying the same request; a repeat
              returns the original generation without charging again. Reusing it
              with a different body returns 409.
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            example:
              aspect_ratio: '16:9'
              generate_image_count: 1
              model: gemini-2.5-flash-image
              prompt: A red fox resting in autumn leaves, soft morning light
            schema:
              $ref: '#/components/schemas/CreateImageRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthenticated
                  message: >-
                    This API key is not valid. Create a new one in Settings →
                    Team.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: API key missing, invalid, revoked or expired.
        '402':
          content:
            application/json:
              example:
                error:
                  code: payment_required
                  message: >-
                    Insufficient credits: this generation needs 39.6 credits and
                    12.0 are available.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not enough credits.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: API keys can only call the /v1 API.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not allowed for this key or organization.
        '409':
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: >-
                    This idempotency key was already used with a different
                    request.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Idempotency key reused with a different request.
        '422':
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  details:
                    - loc:
                        - body
                        - model
                      msg: Field required
                      type: missing
                  message: Request validation failed.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request failed validation.
        '429':
          content:
            application/json:
              example:
                error:
                  code: rate_limited
                  message: Rate limit exceeded; retry after 12s.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded; see Retry-After.
      security:
        - ApiKey: []
components:
  schemas:
    CreateImageRequest:
      additionalProperties: false
      description: Generate one or more images from a prompt and optional reference images.
      properties:
        aspect_ratio:
          anyOf:
            - type: string
            - type: 'null'
          description: Requested aspect ratio (e.g. 1:1, 16:9, 9:16)
          title: Aspect Ratio
        generate_image_count:
          default: 1
          description: Number of images to generate
          title: Generate Image Count
          type: integer
        gpt_image_preset:
          anyOf:
            - type: string
            - type: 'null'
          description: GPT Image aspect preset used to choose a concrete size
          title: Gpt Image Preset
        gpt_image_size:
          anyOf:
            - type: string
            - type: 'null'
          description: GPT Image concrete WxH size
          title: Gpt Image Size
        idempotency_key:
          anyOf:
            - maxLength: 128
              type: string
            - type: 'null'
          description: >-
            Client-supplied key (≤128 chars); a repeat with the same key returns
            the original generation without re-charging
          title: Idempotency Key
        image_background:
          anyOf:
            - type: string
            - type: 'null'
          description: OpenAI image background setting (transparent, opaque, auto)
          title: Image Background
        image_quality:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Image quality setting; per-model (low|medium|high|xhigh|max for GPT
            Image 2.5, 1K|2K|4K for Gemini). Defaults to the selected model's
            catalog default.
          title: Image Quality
        image_resolution:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Image resolution tier when the selected model exposes one (for
            example 1k or 2k).
          title: Image Resolution
        mask_image:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Optional mask image URL for inpainting/editing
          title: Mask Image
        model:
          anyOf:
            - type: string
            - type: 'null'
          description: AI model identifier (provider specific)
          title: Model
        moderation:
          anyOf:
            - type: string
            - type: 'null'
          description: OpenAI moderation setting (auto, low)
          title: Moderation
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional negative prompt
          title: Negative Prompt
        output_format:
          anyOf:
            - type: string
            - type: 'null'
          description: OpenAI image output format (png, webp, jpeg)
          title: Output Format
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Project scope for the generated asset (optional)
          title: Project Id
        prompt:
          description: Text prompt for image generation
          title: Prompt
          type: string
        reference_images:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. List of reference image URLs for image-to-image editing
          title: Reference Images
        reference_names:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                type: array
              type: object
            - type: 'null'
          description: User-facing aliases for reference images, keyed by reference_images
          title: Reference Names
        response_format:
          anyOf:
            - type: string
            - type: 'null'
          description: OpenAI image response format (b64_json, url)
          title: Response Format
      required:
        - prompt
      title: CreateImageRequest
      type: object
    GenerationResponse:
      description: >-
        One generation. Poll GET /v1/generations/{id} until status is completed
        or failed.
      properties:
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Completed At
        created_at:
          format: date-time
          title: Created At
          type: string
        credits_charged:
          anyOf:
            - type: number
            - type: 'null'
          description: Credits actually charged; null while pending.
          title: Credits Charged
        error:
          anyOf:
            - $ref: '#/components/schemas/GenerationError'
            - type: 'null'
        id:
          examples:
            - 6f1c2d3e-9a0b-4c7d-8e1f-2a3b4c5d6e7f
          title: Id
          type: string
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
        model:
          examples:
            - seedance-2-5-fal
          title: Model
          type: string
        outputs:
          items:
            $ref: '#/components/schemas/GenerationOutput'
          title: Outputs
          type: array
        prompt:
          title: Prompt
          type: string
        status:
          enum:
            - pending
            - completed
            - failed
          title: Status
          type: string
        type:
          enum:
            - image
            - video
            - audio
          title: Type
          type: string
      required:
        - id
        - type
        - status
        - model
        - prompt
        - created_at
      title: GenerationResponse
      type: object
    ErrorResponse:
      description: Every non-2xx /v1 response.
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
      title: ErrorResponse
      type: object
    GenerationError:
      properties:
        code:
          description: >-
            One of the public failure categories: rate_limited, timeout, safety,
            invalid_voice, invalid_request, billing_or_access, provider_auth,
            provider_unavailable, provider_error.
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: GenerationError
      type: object
    GenerationOutput:
      properties:
        asset_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Workspace asset id for this output. Pass it as a reference input to
            chain generations.
          title: Asset Id
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          examples:
            - video/mp4
          title: Content Type
        duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Seconds
        height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Height
        url:
          description: >-
            Download URL. Fetch promptly or store the file; URLs are not
            permanent.
          title: Url
          type: string
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
      required:
        - url
      title: GenerationOutput
      type: object
    ErrorBody:
      properties:
        code:
          description: >-
            Stable machine-readable code: unauthenticated, invalid_api_key,
            payment_required, forbidden, api_key_scope, not_found, conflict,
            validation_error, rate_limited, client_error, internal_error.
          title: Code
          type: string
        details:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: >-
            Only on 422: one entry per offending field, with `loc`, `msg` and
            `type`.
          title: Details
        message:
          description: >-
            Human-readable explanation; safe to show to a developer, not meant
            for parsing.
          title: Message
          type: string
        trace_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Quote this when contacting support; it identifies the exact request.
          title: Trace Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
  securitySchemes:
    ApiKey:
      bearerFormat: ek_live_…
      description: >-
        An organization API key created in Settings → Team, sent as
        `Authorization: Bearer <key>`.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.