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

# GPT Image 2 Generation

> Generate and edit images with GPT Image 2

<Tip>
  1. After submission, a `task_id` is returned. If you provide a `callback_url`, Vidgo API sends a POST request when the task becomes `finished` or `failed`.
  2. You can always retrieve the result with the unified [Query Task Status](/api-manual/task-management/status) endpoint.
</Tip>

# GPT Image 2 Generation

## Overview

Use Vidgo API to generate a single image from a prompt or edit one or more reference images with natural-language instructions. GPT Image 2 supports explicit quality tiers, ratio presets, custom dimensions, and `1K`, `2K`, or `4K` resolution control.

## Available Models

* **gpt-image-2** - Text-to-image generation from a prompt.
* **gpt-image-2-edit** - Image editing based on one or more `image_urls` and a text instruction.

## Notes

* `input.prompt` is required and supports up to `4000` characters.
* `input.quality` is optional: `low`, `medium`, or `high`. Default: `low`.
* `input.size` is optional. Supported values are `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `16:9`, `9:16`, `21:9`, or a custom `WIDTHxHEIGHT` value.
* `input.resolution` is optional: `1K`, `2K`, or `4K`.
* `gpt-image-2-edit` requires `input.image_urls`.
* `gpt-image-2` does not accept `input.image_urls`.
* Each request returns one image.
* `n` is not supported for GPT Image 2 requests.

## Resolution

The `resolution` parameter controls the effective output resolution and credits cost.

| Resolution | Credits multiplier | Description                                       |
| ---------- | -----------------: | ------------------------------------------------- |
| `1K`       |                 1x | Standard resolution                               |
| `2K`       |                 2x | High resolution                                   |
| `4K`       |                 4x | Ultra-high resolution for true 4K-supported sizes |

### Billing by Quality

| Quality |         1K |         2K |         4K |
| ------- | ---------: | ---------: | ---------: |
| Low     |  2 credits |  4 credits |  8 credits |
| Medium  |  3 credits |  6 credits | 12 credits |
| High    | 12 credits | 24 credits | 48 credits |

## Resolution Rules

* If `size` is omitted or set to `auto`, the request is processed and billed as `1K`, even if `resolution` is provided.
* Custom `WIDTHxHEIGHT` sizes require `resolution` `2K` or `4K`.
* `4K` billing applies only to `16:9`, `9:16`, `21:9`, or custom sizes with a `3840`-pixel edge.
* A `4K` request that does not meet the true 4K rule is billed at the effective `2K` tier.
* A custom size whose longest edge is `3840` must use `resolution: "4K"`.

## Custom Size Constraints

Custom sizes use `WIDTHxHEIGHT` format, for example `2304x1536`, and must satisfy all of the following:

* Width and height must both be divisible by `16`.
* The maximum edge length is `3840` pixels.
* The aspect ratio must not exceed `3:1`.
* Total pixel count must stay between `655,360` and `8,294,400`.

## Request Examples

````bash theme={null}
### Generate Image

```bash
curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header "Authorization: Bearer VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A premium product photo of a silver espresso machine on a clean white studio background, realistic lighting, high detail",
      "quality": "low",
      "size": "1:1",
      "resolution": "1K"
    }
  }'
````

### Edit Image

```bash theme={null}
curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header "Authorization: Bearer VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2-edit",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "Replace the background with a clean white studio backdrop and add a soft natural shadow while preserving the product shape",
      "quality": "medium",
      "size": "1:1",
      "resolution": "2K",
      "image_urls": [
        "https://example.com/reference-product.jpg"
      ]
    }
  }'
```

## Response Flow

The submit endpoint returns a `task_id`, `status`, and `created_time`. If you provide `callback_url`, Vidgo API sends a POST request when the task reaches `finished` or `failed`.

Use the unified status endpoint to retrieve the final result:

```bash theme={null}
curl --request GET \
  --url https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  --header "Authorization: Bearer VIDGO_API_KEY"
```

When the task is `finished`, the status response includes generated image file URLs in `data.files`. If the task fails, the status payload returns the failure details for troubleshooting.


## OpenAPI

````yaml /api-manual/image-series/gpt-image-2.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - GPT Image 2 API
  description: >-
    Generate or edit one image per request with GPT Image 2 on Vidgo API.
    Supports quality tiers, ratio presets, custom dimensions, and explicit 1K,
    2K, or 4K resolution control.
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - GPT Image 2
      summary: Submit GPT Image 2 Task
      description: >-
        Generate or edit one image using GPT Image 2 on Vidgo API. Use
        gpt-image-2 for prompt-based generation and gpt-image-2-edit when you
        need reference image URLs. The n parameter is not supported.
      operationId: submitGPTImage2Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              gpt-image-2:
                summary: gpt-image-2
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A premium product photo of a silver espresso machine on a
                      clean white studio background, realistic lighting, high
                      detail
                    quality: low
                    size: '1:1'
                    resolution: 1K
              gpt-image-2-2k:
                summary: gpt-image-2-2k
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A clean landing-page hero illustration of a fintech
                      dashboard with crisp typography and balanced spacing
                    quality: medium
                    size: '16:9'
                    resolution: 2K
              gpt-image-2-4k:
                summary: gpt-image-2-4k
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A cinematic 21:9 hero image of an electric concept car in
                      a rain-soaked city at night
                    quality: high
                    size: '21:9'
                    resolution: 4K
              gpt-image-2-custom-size:
                summary: gpt-image-2-custom-size
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A product marketing banner with a centered smartwatch,
                      soft reflections, and clean negative space for headline
                      copy
                    quality: medium
                    size: 2304x1536
                    resolution: 2K
              gpt-image-2-edit:
                summary: gpt-image-2-edit
                value:
                  model: gpt-image-2-edit
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      Replace the background with a clean white studio backdrop
                      and add a soft natural shadow while preserving the product
                      shape
                    quality: medium
                    size: '1:1'
                    resolution: 2K
                    image_urls:
                      - https://example.com/reference-product.jpg
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_prompt:
                  value:
                    code: 400
                    error:
                      message: prompt is required
                      type: invalid_request_error
                unsupported_n:
                  value:
                    code: 400
                    error:
                      message: n is not supported for gpt-image-2
                      type: invalid_request_error
                missing_image_urls_for_edit:
                  value:
                    code: 400
                    error:
                      message: image_urls is required for edit
                      type: invalid_request_error
                image_urls_not_supported_for_generate:
                  value:
                    code: 400
                    error:
                      message: image_urls is only supported for gpt-image-2-edit
                      type: invalid_request_error
                custom_size_requires_higher_resolution:
                  value:
                    code: 400
                    error:
                      message: custom size requires resolution 2K or 4K
                      type: invalid_request_error
                true_4k_custom_size_requires_4k:
                  value:
                    code: 400
                    error:
                      message: true 4K custom size requires resolution 4K
                      type: invalid_request_error
                invalid_quality:
                  value:
                    code: 400
                    error:
                      message: 'quality must be one of: low, medium, high'
                      type: invalid_request_error
                invalid_resolution:
                  value:
                    code: 400
                    error:
                      message: 'resolution must be one of: 1K, 2K, 4K'
                      type: invalid_request_error
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 401
                error:
                  message: Unauthorized - Invalid API key
                  type: authentication_error
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: >-
            GPT Image 2 model identifier. Use gpt-image-2 for prompt-based
            generation and gpt-image-2-edit when you need reference image URLs
            for editing.
          enum:
            - gpt-image-2
            - gpt-image-2-edit
          example: gpt-image-2
        callback_url:
          type: string
          format: uri
          description: Webhook callback URL for finished or failed task notifications.
          example: https://your-domain.com/callback
        input:
          type: object
          required:
            - prompt
          description: Input parameters for GPT Image 2 generation or editing on Vidgo API.
          properties:
            prompt:
              type: string
              description: Prompt describing the desired image or edit.
              maxLength: 4000
              example: A studio product photo of a matte black espresso machine
            quality:
              type: string
              description: >-
                Image quality tier. Defaults to low and determines the credit
                cost together with the effective resolution.
              enum:
                - low
                - medium
                - high
              default: low
              example: low
            size:
              description: >-
                Image size. Use auto, a supported aspect ratio, or a custom
                WIDTHxHEIGHT value. If size is omitted or set to auto, the
                request is processed at the 1K tier.
              oneOf:
                - type: string
                  enum:
                    - auto
                    - '1:1'
                    - '2:3'
                    - '3:2'
                    - '3:4'
                    - '4:3'
                    - '4:5'
                    - '5:4'
                    - '16:9'
                    - '9:16'
                    - '21:9'
                  description: Preset size or aspect ratio
                - type: string
                  pattern: ^\d{3,4}x\d{3,4}$
                  description: Custom dimensions as WIDTHxHEIGHT
              example: '16:9'
            resolution:
              type: string
              description: >-
                Requested resolution. Custom sizes require 2K or 4K. If size is
                auto, the effective result stays at 1K. Non-true-4K requests may
                be billed at the effective 2K tier.
              enum:
                - 1K
                - 2K
                - 4K
              example: 1K
            image_urls:
              type: array
              description: >-
                Reference image URLs for edit requests. Required for
                gpt-image-2-edit and rejected for gpt-image-2.
              items:
                type: string
                format: uri
              example:
                - https://example.com/reference-product.jpg
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
              example: not_started
            created_time:
              type: string
              format: date-time
              example: '2026-04-27T10:30:00'
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication.


        Get your API key from the API Key Management page and pass it in the
        request header:


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````