GPT Image 2 Image to Image API Documentation

Generate edited or transformed images using the gpt-image-2-image-to-image model

Overview

This document describes how to use the gpt-image-2-image-to-image model for image editing and image-to-image generation.

The integration flow consists of two steps:

1. Create a generation task
2. Query task status and results

Authentication

All API requests require a Bearer Token in the request header:

Authorization: Bearer YOUR_API_KEY

Get API Key:

1. Open the API Keys page
2. Click Create API Key
3. Add the key to the request header: Authorization: Bearer YOUR_API_KEY

1. Create Generation Task

API Information

• URL: POST https://aigptimage.com/api/v1/jobs/createTask
• Content-Type: application/json

Request Parameters

Model Parameter

The model parameter specifies which public image editing model to use.

Note: The model value must match exactly and use the public model ID shown on this page.

input Object Parameters

prompt

• Type: string
• Required: Yes
• Description: Text prompt describing how the source image should be edited or transformed
• Max Length: 20000 characters

input_urls

• Type: string[]
• Required: Yes
• Description: Source image URLs. This is the recommended field for GPT Image 2 image-to-image requests
• Constraints: At least one valid image URL is required
• Supported URL Format: Publicly accessible https:// image URLs
• Supported Image Types: JPEG/JPG, PNG, WEBP
• Max File Size: 30MB per image
• Not Supported: Raw base64 strings and inline data:image/...;base64,... URLs are not supported. If you only have a local file, host it on your own storage, CDN, server, or image hosting service first, then pass the resulting public image URL

image_urls

• Type: string[]
• Required: No
• Description: Compatibility alias accepted by the public API and mapped to input_urls. Prefer input_urls for new integrations
• Supported URL Format: Publicly accessible https:// image URLs
• Supported Image Types: JPEG/JPG, PNG, WEBP
• Max File Size: 30MB per image
• Not Supported: Raw base64 strings and inline data:image/...;base64,... URLs are not supported

image_input

• Type: string[]
• Required: No
• Description: Compatibility image input field accepted by the public API when provided. Prefer input_urls or image_urls for this model
• Supported URL Format: Publicly accessible https:// image URLs
• Supported Image Types: JPEG/JPG, PNG, WEBP
• Max File Size: 30MB per image
• Not Supported: Raw base64 strings and inline data:image/...;base64,... URLs are not supported

How to Provide Source Image URLs

For input_urls, pass URLs that the API can fetch directly over the public internet.

The API does not accept local file paths, binary file uploads, or embedded base64 data in the create task request. The API caller must host the source image first, then provide the hosted image URL:

{
  "input_urls": ["https://cdn.example.com/input.png"]
}

aspect_ratio

• Type: string
• Required: No
• Description: Output image aspect ratio
• Options: auto, 1:1, 5:4, 9:16, 21:9, 16:9, 4:3, 3:2, 4:5, 3:4, 2:3
• Default Value: auto

resolution

• Type: string
• Required: No
• Description: Output resolution used for generation and billing
• Options: 1K, 2K, 4K
• Default Value: 1K
• Important: When aspect_ratio is auto or omitted, only 1K is supported. 2K or 4K with auto will fail to create. 4K is also not supported with aspect_ratio: "1:1"

Request Example

{
  "model": "gpt-image-2-image-to-image",
  "input": {
    "prompt": "Turn this product photo into a premium studio advertisement with dramatic rim lighting",
    "input_urls": ["https://cdn.example.com/input.png"],
    "resolution": "1K"
  }
}

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxxxxxxxxxxxx"
  }
}

Response Parameters

2. Query Task Status

API Information

• URL: GET https://aigptimage.com/api/v1/jobs/recordInfo
• Parameter: taskId (URL query parameter)

Request Example

GET https://aigptimage.com/api/v1/jobs/recordInfo?taskId=task_xxxxxxxxxxxxx

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxxxxxxxxxxxx",
    "model": "gpt-image-2-image-to-image",
    "state": "waiting",
    "param": "{\"model\":\"gpt-image-2-image-to-image\",\"input\":{\"prompt\":\"Turn this product photo into a premium studio advertisement with dramatic rim lighting\",\"input_urls\":[\"https://cdn.example.com/input.png\"],\"resolution\":\"1K\"}}",
    "resultJson": null,
    "failCode": null,
    "failMsg": null,
    "costTime": null,
    "completeTime": null,
    "createTime": 1757584164490
  }
}

Response Parameters

Success Result Structure

For image editing tasks, resultJson usually has this structure:

{
  "resultUrls": ["https://your-cdn.example.com/result-1.png"]
}

Usage Flow

1. Host or prepare a public HTTPS source image URL
2. Call POST /api/v1/jobs/createTask
3. Extract taskId from the response
4. Poll GET /api/v1/jobs/recordInfo?taskId=...
5. Read output image URLs from resultJson when the task succeeds

Notes

• API calls use the same credit balance and billing rules as the web app
• Only send trusted and stable public image URLs
• Do not send embedded base64 image data. Inline data:image/...;base64,... values may be accepted as JSON strings by the request parser, but they are not supported image inputs for this model
• resolution affects both output size and credit consumption

Error Codes