ccapi-ai GPT Image 2 Per-Call Image Generation API

openapi: 3.2.0
info:
  title: CCAPI GPT Image 2 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: GPT Image 2 Per-Call Image Generation
  description: 'Access GPT Image 2 via CCAPI''s OpenAI Images-compatible API.


    ---


    ## What This Document Covers


    This document corresponds to the **per-call billing version**, using `POST /v1/images/generations` as the unified endpoint.


    ## Endpoint


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


    This endpoint behaves **synchronously** by default: submit a task and receive the generated image directly in the response (after internal polling, up to ~60s). No task ID or manual polling is required.


    ## 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 via Bunny CDN


    ## Supported Models


    | Model Name | Description | Pricing |

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

    | `gpt-image-2` | GPT Image 2, 1080P high quality | $0.211 / image (official) |


    ## Official Pricing


    - **gpt-image-2**: $0.211 per 1080P high quality image

    - CCAPI user price: $0.02 (with gpt-image-A group rate applied)


    ## Request Format


    Uses the OpenAI Images-compatible format:

    - `model`: Use `gpt-image-2`

    - `prompt`: Text-to-image prompt

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


    ## Key Field Descriptions


    ### `model`

    Use `gpt-image-2` for GPT Image 2 generation.


    ### `prompt`

    Text description of the image to generate.


    ### `image` (optional)

    - Not provided: text-to-image

    - Single string: single-image image-to-image

    - String array: multi-image blending


    It is recommended to pass publicly accessible image URLs.


    ### `response_format` (optional)

    - `url` (default): Returns a CDN URL

    - `b64_json`: Returns base64-encoded image data


    ### `size` (optional)

    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.


    ---


    ## Response Description


    - Response structure follows the OpenAI Images style

    - Synchronous: image is returned directly in the response after internal polling (~60s max)

    - `data[0].url` — the final accessible image URL (hosted via Bunny CDN)

    - `data[0].revised_prompt` — the normalized prompt'
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:
      - GPT Image 2 Per-Call Image Generation
      x-apifox-folder: Image/GPT Image 2
  /v1/images/generations/async:
    post:
      deprecated: false
      description: 'Unified asynchronous image generation endpoint. Choose the matching request schema branch based on `model`, such as GPT Image 2 or Midjourney Imagine.


        The response immediately returns a `task_id`; poll `GET /v1/images/tasks/{task_id}` for status and results.'
      operationId: openai-compatible-async-image-generation
      parameters: []
      requestBody:
        content:
          application/json:
            examples:
              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
              midjourney-imagine-api_imagine_fast:
                summary: Fast Imagine task
                value:
                  mode: fast
                  model: mj_imagine
                  prompt: A small red fox reading a book under warm lantern light, watercolor illustration --no text
              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
            schema:
              oneOf:
              - description: GPT Image 2 async generation request body. Identical to the synchronous endpoint.
                properties:
                  image:
                    description: Optional. Reference image URL(s) for image-to-image or multi-image blending. Single URL string or an array of URL strings.
                    oneOf:
                    - example: https://example.com/photo.jpg
                      type: string
                    - items:
                        type: string
                      type: array
                  model:
                    default: gpt-image-2
                    enum:
                    - gpt-image-2
                    example: gpt-image-2
                    type: string
                  prompt:
                    description: Text description of the image to generate.
                    example: A serene mountain landscape at sunset with vibrant orange and purple skies
                    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
              - properties:
                  mode:
                    default: fast
                    description: Generation speed. Defaults to `fast`.
                    enum:
                    - relax
                    - fast
                    - turbo
                    example: fast
                    type: string
                  model:
                    default: mj_imagine
                    description: Use `mj_imagine`.
                    enum:
                    - mj_imagine
                    example: mj_imagine
                    type: string
                  prompt:
                    description: Image description. Midjourney prompt parameters may be included.
                    example: A small red fox reading a book under warm lantern light, watercolor illustration --no text
                    type: string
                required:
                - model
                - prompt
                title: Midjourney Imagine API
                type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                code: success
                data:
                  created: 1773294301
                  model: gpt-image-2
                  status: queued
                  task_id: task_7b3f1c9e2a
                message: submitted
              schema:
                $ref: '#/components/schemas/ImageAsyncSubmitResponse'
          description: Task accepted; poll for the result
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request parameters
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions or current group unavailable
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Submission failed
      security:
      - bearer: []
      summary: Submit Async Image Task
      tags:
      - GPT Image 2 Per-Call Image Generation
      x-apifox-folder: Image/GPT Image 2
  /v1/images/tasks/{task_id}:
    get:
      deprecated: false
      description: Poll an asynchronous image task by `task_id`. On success, single-image tasks use `result_url`; tasks with split outputs use ordered `result_urls` and may provide a composite `preview_url`.
      operationId: openai-compatible-async-image-task-fetch
      parameters:
      - description: The task_id returned by the async submit endpoint.
        example: task_7b3f1c9e2a
        in: path
        name: task_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  summary: Still generating
                  value:
                    code: success
                    data:
                      progress: 50%
                      status: IN_PROGRESS
                      task_id: task_7b3f1c9e2a
                succeeded:
                  summary: Completed
                  value:
                    code: success
                    data:
                      progress: 100%
                      result_url: https://cdn.ccapi.ai/images/generated/gpt-image-2/1773294301681-0.png
                      status: SUCCESS
                      task_id: task_7b3f1c9e2a
              schema:
                $ref: '#/components/schemas/ImageAsyncTaskResponse'
          description: Task status and result
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '404':
          content:
            application/json:
              example:
                code: task_not_exist
                message: task not found
              schema:
                $ref: '#/components/schemas/ImageAsyncTaskResponse'
          description: Task not found for this user
      security:
      - bearer: []
      summary: Get Async Image Task
      tags:
      - GPT Image 2 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
    ImageAsyncSubmitResponse:
      description: Acknowledgement returned by the async submit endpoint.
      properties:
        code:
          example: success
          type: string
        data:
          properties:
            created:
              description: Submission timestamp.
              type: integer
            model:
              example: gpt-image-2
              type: string
            status:
              example: queued
              type: string
            task_id:
              description: Poll GET /v1/images/tasks/{task_id} with this id.
              type: string
          required:
          - task_id
          - status
          type: object
        message:
          example: submitted
          type: string
      required:
      - code
      - data
      type: object
    GPTImage2ImageResponse:
      properties:
        created:
          description: Generation timestamp.
          type: integer
        data:
          items:
            $ref: '#/components/schemas/GPTImage2ImageData'
          type: array
      required:
      - created
      - data
      type: object
    ImageAsyncTaskResponse:
      description: Status and result of an async image task.
      properties:
        code:
          example: success
          type: string
        data:
          properties:
            fail_reason:
              description: Failure detail. Present when status is FAILURE.
              type: string
            preview_url:
              description: Optional composite preview URL for multi-result image tasks.
              type: string
            progress:
              example: 100%
              type: string
            result_url:
              description: Final image URL. Present when status is SUCCESS.
              type: string
            result_urls:
              description: Ordered image URLs when an async provider returns multiple split results.
              items:
                type: string
              type: array
            status:
              description: 'One of: SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS, FAILURE.'
              example: SUCCESS
              type: string
            task_id:
              type: string
          required:
          - task_id
          - status
          type: object
        message:
          type: string
      required:
      - code
      - 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