ccapi-ai Gemini Per-Call Image Generation API

openapi: 3.2.0
info:
  title: CCAPI Gemini Per-Call Image Generation API
  description: CCAPI Model Gateway — OpenAI-compatible unified API
  version: 1.0.0
servers:
- url: https://api.ccapi.ai
  description: CCAPI API Gateway
tags:
- name: Gemini Per-Call Image Generation
  description: 'Access Gemini per-call image generation capabilities via CCAPI''s OpenAI Images-compatible API. The public model name is the `nano-banana` series.


    ---


    ## What This Document Covers


    This document corresponds to the **per-call billing version**, using `POST /v1/images/generations` as the unified endpoint, suitable for scenarios where you want to call the API on a per-image/tier basis.


    If you want to use the **Google AI Studio API native request format**, please refer to the separate Gemini native image generation document instead of this file.


    ---


    ## Endpoint


    Use `POST /v1/images/generations` as the unified endpoint.


    This is a synchronous API. Upon successful request, image results are returned directly without polling.


    ---


    ## Authentication


    Use `Authorization: Bearer `.


    ---


    ## Response Characteristics


    - Response structure follows the OpenAI Images style

    - The platform returns image URLs by default

    - The platform normalizes and hosts image results uniformly, without exposing underlying provider details


    ---


    ## Supported Models


    | Model Name | Capability Mapping | Resolution Tier | Description |

    |---|---|---|---|

    | `nano-banana` | Gemini 2.5 Flash Image | 1K | Basic |

    | `nano-banana-pro-1k` | Gemini 3 Pro Image Preview | 1K | Pro |

    | `nano-banana-pro-2k` | Gemini 3 Pro Image Preview | 2K | Pro |

    | `nano-banana-pro-4k` | Gemini 3 Pro Image Preview | 4K | Pro |

    | `nano-banana-2-0.5k` | Gemini 3.1 Flash Image Preview | 0.5K | Gen 2 |

    | `nano-banana-2-1k` | Gemini 3.1 Flash Image Preview | 1K | Gen 2 |

    | `nano-banana-2-2k` | Gemini 3.1 Flash Image Preview | 2K | Gen 2 |

    | `nano-banana-2-4k` | Gemini 3.1 Flash Image Preview | 4K | Gen 2 |


    The resolution is already encoded in the public model name, e.g. `nano-banana-pro-2k`, `nano-banana-2-4k`.


    ---


    ## Request Format


    Uses the OpenAI Images-compatible format:


    - `model`: Use the platform''s public model name

    - `prompt`: Text-to-image prompt

    - `image`: Optional, supports single or multiple reference image inputs for image-to-image and multi-image blending

    - `aspect_ratio`: Optional, passed as a top-level field


    ---


    ## Aspect Ratio Support


    ### `nano-banana` / `nano-banana-pro-*`


    Supported: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`


    ### `nano-banana-2-*`


    In addition to the above ratios, also supports: `1:4`, `4:1`, `1:8`, `8:1`


    ---


    ---


    ## Pricing


    Visit the Pricing page to see full model pricing for this provider.'
paths:
  /v1/images/generations:
    post:
      deprecated: false
      description: 'Unified OpenAI-compatible image endpoint. Choose the matching oneOf request schema branch for GPT Image 2, Gemini nano-banana, Z-Image Turbo, or CCAPI Upscale based on the `model` value.


        Scalar may list this operation under multiple image provider groups, but they all point to the same real callable route: `POST /v1/images/generations`.'
      operationId: openai-compatible-image-generation
      parameters: []
      requestBody:
        content:
          application/json:
            examples:
              ccapi-image-upscale_default:
                image: https://example.com/input.jpg
                model: ccapi-upscale-v1
                model_quality: MQ
                response_format: url
              gemini-per-call-image-generation_image_to_image:
                summary: Image-to-image
                value:
                  image: https://example.com/photo.jpg
                  model: nano-banana-pro-2k
                  prompt: Transform this portrait into anime style while keeping facial features recognizable
              gemini-per-call-image-generation_long_poster:
                summary: Long poster
                value:
                  aspect_ratio: '1:4'
                  model: nano-banana-2-4k
                  prompt: A vertical sci-fi movie poster with neon city lights and one astronaut silhouette
              gemini-per-call-image-generation_multi_image_blend:
                summary: Multi-image blending
                value:
                  aspect_ratio: '16:9'
                  image:
                  - https://example.com/reference-1.png
                  - https://example.com/reference-2.png
                  model: nano-banana-2-4k
                  prompt: Blend these two reference images into a new unified-style image, preserving the main elements from both, suitable for a landscape poster
              gemini-per-call-image-generation_text_to_image:
                summary: Text-to-image
                value:
                  model: nano-banana-2-4k
                  prompt: A cute cat sitting on a windowsill, watercolor style
              image_to_image:
                summary: Image-to-image with reference
                value:
                  image: https://example.com/photo.jpg
                  model: gpt-image-2
                  prompt: Transform this portrait into anime style while keeping facial features recognizable
              multi_image_blend:
                summary: Multi-image blending
                value:
                  image:
                  - https://example.com/reference-1.png
                  - https://example.com/reference-2.png
                  model: gpt-image-2
                  prompt: Blend these two reference images into a new unified-style image, preserving the main elements from both
              text_to_image:
                summary: Text-to-image
                value:
                  model: gpt-image-2
                  prompt: A serene mountain landscape at sunset with vibrant orange and purple skies
              z-image-turbo_poster:
                summary: Bilingual editorial poster
                value:
                  aspect_ratio: '4:3'
                  model: z-image-turbo
                  nsfw_checker: false
                  prompt: Editorial poster of a red bicycle beside a misty forest path, crisp bilingual typography
            schema:
              oneOf:
              - description: GPT Image 2 image generation request body.
                properties:
                  image:
                    description: Optional. Reference image URL(s) for image-to-image or multi-image blending. Can be a single URL string or an array of URL strings.
                    oneOf:
                    - example: https://example.com/photo.jpg
                      type: string
                    - example:
                      - https://example.com/reference-1.png
                      - https://example.com/reference-2.png
                      items:
                        type: string
                      type: array
                  model:
                    default: gpt-image-2
                    description: Platform public model name. Use `gpt-image-2` for GPT Image 2 generation.
                    enum:
                    - gpt-image-2
                    example: gpt-image-2
                    type: string
                  n:
                    default: 1
                    description: Number of images to generate.
                    minimum: 1
                    type: integer
                  prompt:
                    description: Text description of the image to generate.
                    example: A serene mountain landscape at sunset with vibrant orange and purple skies
                    type: string
                  response_format:
                    default: url
                    description: Response format. `url` returns a CDN URL, `b64_json` returns base64-encoded image data.
                    enum:
                    - url
                    - b64_json
                    type: string
                  size:
                    description: Requested image dimensions. Task-based channels translate this value to a supported aspect ratio; exact output pixels are provider-defined and may differ from the request. Omit it to use the platform default.
                    type: string
                required:
                - prompt
                title: GPT Image 2 Per-Call Image Generation
                type: object
              - description: Gemini per-call image generation request body.
                properties:
                  aspect_ratio:
                    description: Output aspect ratio, passed as a top-level field. When omitted, the platform does not inject a default value; the actual behavior follows the upstream model. `nano-banana` and `nano-banana-pro-*` support standard ratios; `nano-banana-2-*` additionally supports `1:4`, `4:1`, `1:8`, `8:1`. This field only changes the canvas ratio, not the model tier or pricing tier.
                    enum:
                    - '1:1'
                    - '1:4'
                    - '1:8'
                    - '2:3'
                    - '3:2'
                    - '3:4'
                    - '4:1'
                    - '4:3'
                    - '4:5'
                    - '5:4'
                    - '8:1'
                    - '9:16'
                    - '16:9'
                    - '21:9'
                    example: '16:9'
                    type: string
                  image:
                    description: Image-to-image or multi-image blending input. Pass a string for a single image, or a string array for multiple images. When this field is not provided, the request is treated as text-to-image. It is recommended to pass publicly accessible image URLs. If using Base64, the client should wrap it as a `data:image/png;base64,...` string; the platform will not automatically convert raw Base64 to an image reference.
                    oneOf:
                    - example: https://example.com/photo.jpg
                      type: string
                    - example:
                      - https://example.com/reference-1.png
                      - https://example.com/reference-2.png
                      items:
                        type: string
                      type: array
                  model:
                    description: Platform public model name. The resolution is already encoded in the model name, so no additional tier selection is needed. `nano-banana` is the basic version fixed at 1K; `nano-banana-pro-*` is for 1K / 2K / 4K standard high-quality images; `nano-banana-2-*` is for 0.5K / 1K / 2K / 4K Gen 2 image capabilities with support for ultra-wide formats.
                    enum:
                    - gemini-2.5-flash-image
                    - nano-banana
                    - nano-banana-pro-1k
                    - nano-banana-pro-2k
                    - nano-banana-pro-4k
                    - nano-banana-2-0.5k
                    - nano-banana-2-1k
                    - nano-banana-2-2k
                    - nano-banana-2-4k
                    example: nano-banana-2-4k
                    type: string
                  prompt:
                    description: Image generation prompt.
                    example: A cute cat sitting on a windowsill, watercolor style
                    type: string
                required:
                - model
                - prompt
                title: Gemini Per-Call Image Generation
                type: object
              - description: CCAPI image upscale request body.
                properties:
                  image:
                    description: Required input image. Pass exactly one image as a URL string, raw base64 string, data URL string, or a one-item string array. Both width and height must be between 256 and 1024 px and the file must be no larger than 5 MB; use gpt-image-2 for images larger than 1K.
                    example: https://example.com/input.jpg
                    oneOf:
                    - type: string
                    - items:
                        type: string
                      maxItems: 1
                      minItems: 1
                      type: array
                  jpg_quality:
                    default: 95
                    description: JPEG quality for JPEG output.
                    maximum: 100
                    minimum: 1
                    type: integer
                  model:
                    default: ccapi-upscale-v1
                    description: Platform public model name. Use `ccapi-upscale-v1` for x2 image super-resolution.
                    enum:
                    - ccapi-upscale-v1
                    type: string
                  model_quality:
                    default: MQ
                    description: Upscale quality hint passed to the upstream provider.
                    enum:
                    - HQ
                    - MQ
                    - LQ
                    type: string
                  response_format:
                    default: url
                    description: Response format. `url` returns an image URL; `b64_json` returns base64-encoded image data.
                    enum:
                    - url
                    - b64_json
                    type: string
                  result_format:
                    default: 0
                    description: Upstream output format option.
                    type: integer
                  return_url:
                    description: Whether upstream should return an image URL. If omitted, CCAPI derives it from `response_format == "url"`.
                    type: boolean
                required:
                - model
                - image
                title: CCAPI Image Upscale
                type: object
              - additionalProperties: false
                description: Z-Image Turbo text-to-image request.
                properties:
                  aspect_ratio:
                    description: Required output canvas ratio.
                    enum:
                    - '1:1'
                    - '4:3'
                    - '3:4'
                    - '16:9'
                    - '9:16'
                    type: string
                  model:
                    default: z-image-turbo
                    description: CCAPI public model name.
                    enum:
                    - z-image-turbo
                    type: string
                  nsfw_checker:
                    description: Optional upstream content-checking switch. Explicit false is sent unchanged.
                    type: boolean
                  prompt:
                    description: Text description of the image to generate, up to 1000 characters.
                    maxLength: 1000
                    minLength: 1
                    type: string
                required:
                - model
                - prompt
                - aspect_ratio
                title: Z-Image Turbo
                type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                single_image:
                  summary: Single image response
                  value:
                    created: 1773294301
                    data:
                    - revised_prompt: A serene mountain landscape at sunset with vibrant orange and purple skies
                      url: https://cdn.ccapi.ai/images/generated/gpt-image-2/1773294301681-0.png
              schema:
                $ref: '#/components/schemas/GPTImage2ImageResponse'
          description: Image generated successfully
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: prompt is required
                  param: prompt
                  type: invalid_request_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request parameters
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid Authentication
                  param: null
                  type: invalid_request_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '403':
          content:
            application/json:
              example:
                error:
                  code: permission_denied
                  message: No permission to use this model
                  param: null
                  type: new_api_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions or current group unavailable
        '500':
          content:
            application/json:
              example:
                error:
                  code: do_request_failed
                  message: Image generation failed
                  param: null
                  type: server_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Generation failed
      security:
      - bearer: []
      summary: Generate or Upscale Image
      tags:
      - Gemini Per-Call Image Generation
      x-apifox-folder: Image/GPT Image 2
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code: {}
            message:
              type: string
            param: {}
            type:
              type: string
          required:
          - message
          - type
          type: object
      required:
      - error
      type: object
    GPTImage2ImageData:
      properties:
        b64_json:
          description: Base64-encoded image data (when response_format is b64_json).
          type: string
        revised_prompt:
          description: Normalized prompt from the platform.
          type:
          - string
          - 'null'
        url:
          description: Final URL of the generated image.
          type: string
      required:
      - url
      type: object
    GPTImage2ImageResponse:
      properties:
        created:
          description: Generation timestamp.
          type: integer
        data:
          items:
            $ref: '#/components/schemas/GPTImage2ImageData'
          type: array
      required:
      - created
      - data
      type: object
  securitySchemes:
    bearer:
      description: 'CCAPI API Key. Format: `Bearer sk-xxx`'
      scheme: bearer
      type: http
x-tagGroups:
- name: Integration Guides
  tags:
  - OpenClaw Integration
  - Hermes Integration
  - Claude Code Integration
  - Codex CLI Integration
  - Gemini CLI Integration
- name: Chat
  tags:
  - Claude / Anthropic LLM Integration
  - OpenAI LLM Integration
  - Google Gemini LLM Integration
  - DeepSeek LLM Integration
  - MiniMax LLM Integration
- name: Image
  tags:
  - GPT Image 2 Per-Call Image Generation
  - Midjourney Imagine API
  - Gemini Per-Call Image Generation
  - CCAPI Image Upscale
  - Z-Image Turbo
  - Doubao Seedream Official Image API
- name: Video
  tags:
  - Gemini Video (Veo 3.1 / Omni Flash)
  - Grok Imagine Video
  - MiniMax H3 Family Video Generation
  - Seedance Trusted Asset Library
  - Seedance 2.5 / 2.0 Video Generation
  - Vidu Video Generation API
- name: Audio
  tags:
  - Producer Task API
  - Suno Task API