# Task: Research and provide the exact API implementation details for OpenAI's gpt-image-1 model. Include:
1. The correct endpoint URL
2. The exact request body structure with all required and optional parameters
3. How to properly handle size parameter (does it go in the request body or elsewhere?)
4. The exact response structure and how to extract the image URL
5. Any special headers or authentication requirements
6. Provide a working example of the full API request with curl or JavaScript fetch
7. Explain any common errors and how to handle them
## Full Output
Below are the practical, exact details you need to call OpenAI’s gpt-image-1 image generation model via the Images API. This covers the correct endpoints, request/response shapes, headers, examples, and common pitfalls.
1) Endpoint URL
- Text-to-image (prompt-based generation):
POST https://api.openai.com/v1/images/generations
- Image edits (supply an existing image and optional mask):
POST https://api.openai.com/v1/images/edits
- Image variations (create variations of an existing image):
POST https://api.openai.com/v1/images/variations
2) Request body structure (all required and optional parameters)
A) Generations (JSON body)
- Endpoint: POST /v1/images/generations
- Content-Type: application/json
- Body fields:
- model (string, required)
Example: "gpt-image-1"
- prompt (string, required)
The natural-language description of the image you want.
- size (string, optional)
Pixel dimensions as "WIDTHxHEIGHT". See details in section 3. Defaults to "1024x1024" if not provided.
- n (integer, optional)
Number of images to generate. Defaults to 1. Not all accounts/models allow n > 1; if unsupported, you’ll receive a 400 error.
- response_format (string, optional)
"url" (default) or "b64_json". Use "url" to receive host-generated URLs; use "b64_json" to receive base64-encoded image data.
- user (string, optional)
An arbitrary end-user identifier to help OpenAI monitor and detect abuse.
Example JSON body (generations):
{
"model": "gpt-image-1",
"prompt": "A watercolor painting of a red fox in a misty forest",
"size": "1024x1024",
"response_format": "url",
"n": 1,
"user": "user-1234"
}
B) Edits (multipart/form-data)
- Endpoint: POST /v1/images/edits
- Content-Type: multipart/form-data
- Fields:
- model (string, required) e.g., gpt-image-1
- image (file, required)
The image to edit. Typically PNG for best results (especially if you rely on transparency). Can be provided as multiple parts named image (or image[]).
- mask (file, optional)
A PNG mask where transparent areas indicate regions to edit. If omitted, transparent areas of the image are used as the mask.
- prompt (string, required)
Text describing how to edit the image.
- size (string, optional)
As above.
- n (integer, optional)
As above (subject to model limits).
- response_format (string, optional)
"url" (default) or "b64_json".
- user (string, optional)
As above.
C) Variations (multipart/form-data)
- Endpoint: POST /v1/images/variations
- Content-Type: multipart/form-data
- Fields:
- model (string, required) e.g., gpt-image-1
- image (file, required)
The image from which to generate variations.
- size (string, optional)
As above.
- n (integer, optional)
As above (subject to model limits).
- response_format (string, optional)
"url" (default) or "b64_json".
- user (string, optional)
As above.
Notes
- The Images API supports the common fields above. Some legacy fields seen in older models (like style or quality) may not apply to gpt-image-1; if you send unsupported fields you’ll get an “Unrecognized request argument” error.
- If you need transparency in edits, provide PNGs and a mask with transparent regions.
3) Handling the size parameter
- Where it goes: size is sent in the request body (not in the URL, not in headers).
- Format: string "WIDTHxHEIGHT", e.g., "256x256", "512x512", "1024x1024".
- Defaults: If omitted, size defaults to "1024x1024".
- Valid values: The safest choices are "256x256", "512x512", or "1024x1024" for gpt-image-1. If you send a size the model doesn’t support, you’ll receive a 400 invalid_request_error.
4) Exact response structure and extracting the image URL
When response_format is "url" (default):
- Shape:
{
"created": 1700000000,
"data": [
{
"url": "https://..."
// Some models may also include "revised_prompt" here
}
]
}
- Extract the URL:
- data[0].url (first image’s URL)
- URL lifetime:
- Returned URLs are temporary and may expire shortly (commonly around 1 hour). If you need permanence, download the image and store it yourself.
When response_format is "b64_json":
- Shape:
{
"created": 1700000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
]
}
- Extract and decode:
- Take data[0].b64_json, base64-decode it, and save to a file (e.g., PNG).
5) Headers and authentication
- Required:
- Authorization: Bearer YOUR_OPENAI_API_KEY
- Content-Type:
- application/json for /images/generations
- multipart/form-data for /images/edits and /images/variations
- Optional:
- OpenAI-Organization: org_...
- OpenAI-Project: proj_...
These optional headers are relevant if your account uses multiple organizations or projects.
- No special beta headers are required for the Images API.
- Always use HTTPS.
6) Working examples
A) cURL: text-to-image (URL response)
curl https://api.openai.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-image-1",
"prompt": "A watercolor painting of a red fox in a misty forest",
"size": "1024x1024",
"response_format": "url",
"n": 1
}'
Expected output (truncated):
{
"created": 1700000000,
"data": [
{
"url": "https://..."
}
]
}
B) cURL: text-to-image (base64 response, saved to file)
curl https://api.openai.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-image-1",
"prompt": "A watercolor painting of a red fox in a misty forest",
"size": "1024x1024",
"response_format": "b64_json"
}' | jq -r '.data[0].b64_json' | base64 --decode > fox.png
C) JavaScript fetch: text-to-image (URL response)
const apiKey = process.env.OPENAI_API_KEY;
async function generateImage() {
const res = await fetch("https://api.openai.com/v1/images/generations", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${apiKey}`
},
body: JSON.stringify({
model: "gpt-image-1",
prompt: "A watercolor painting of a red fox in a misty forest",
size: "1024x1024",
response_format: "url",
n: 1
})
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
console.error("Request failed:", res.status, err);
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();
const url = json.data?.[0]?.url;
console.log("Image URL:", url);
// Tip: download and persist the image if you need a permanent copy
}
generateImage().catch(console.error);
D) JavaScript fetch: text-to-image (base64 response, save to file in Node)
import fs from "node:fs/promises";
const apiKey = process.env.OPENAI_API_KEY;
async function generateImageToFile() {
const res = await fetch("https://api.openai.com/v1/images/generations", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${apiKey}`
},
body: JSON.stringify({
model: "gpt-image-1",
prompt: "A watercolor painting of a red fox in a misty forest",
size: "1024x1024",
response_format: "b64_json"
})
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
console.error("Request failed:", res.status, err);
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();
const b64 = json.data?.[0]?.b64_json;
const buffer = Buffer.from(b64, "base64");
await fs.writeFile("fox.png", buffer);
console.log("Saved to fox.png");
}
generateImageToFile().catch(console.error);
E) cURL: image edit (multipart) with a mask
curl https://api.openai.com/v1/images/edits \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-1" \
-F "image=@./input.png" \
-F "mask=@./mask.png" \
-F 'prompt=A colorful stained-glass effect in the masked area' \
-F "size=1024x1024" \
-F "response_format=url"
7) Common errors and how to handle them
- 400 invalid_request_error
- Examples:
- Missing required fields (e.g., prompt in generations; image in edits/variations).
- Invalid size value or format (must be like "1024x1024").
- Passing unsupported parameters for the model.
- Using n > 1 where not supported (message may say “This model currently only supports n=1”).
- Handling: Validate inputs before calling; check the error.message for details. Adjust size and parameters to supported values.
- 401 unauthorized
- Examples:
- Missing or bad API key.
- Using a test key or one without Images API access.
- Handling: Ensure Authorization header is set to "Bearer YOUR_OPENAI_API_KEY" and the key is valid.
- 404 not_found
- Example: Model name is incorrect (e.g., typo in "gpt-image-1").
- Handling: Verify the model name and endpoint.
- 415 unsupported_media_type (edits/variations)
- Example: Not using multipart/form-data for endpoints that require file uploads.
- Handling: Switch to multipart/form-data and send files with -F or a proper form-data encoder.
- 422 unprocessable_entity (edits/variations)
- Examples:
- Corrupted or unsupported image file.
- Mask dimensions don’t match the image.
- Handling: Re-encode your images as PNG, ensure mask/image sizes match, and keep file sizes reasonable.
- 429 rate_limit_exceeded or server_overloaded
- Examples: Too many requests or momentary service overloads.
- Handling: Implement exponential backoff retries and/or reduce request rate.
- 500 server_error
- Handling: Retry with backoff, and add logging. If persistent, contact support.
- Safety/content policy errors
- Example: The prompt violates content policy; images cannot be generated.
- Handling: Inspect error.message, adjust the prompt to comply with policy.
Error payload shape
On error, the API returns JSON like:
{
"error": {
"message": "Detailed explanation...",
"type": "invalid_request_error",
"param": null,
"code": null
}
}
Practical tips
- URLs expire: If you use response_format=url, download the image promptly and store it yourself.
- Prefer b64_json if you want to store binaries directly without fetching from a URL.
- Keep prompts concise but specific; very long prompts can be counterproductive.
- For edits, ensure your mask PNG uses transparency correctly; transparent pixels indicate areas to edit.
This is all you need to implement gpt-image-1 using the Images API. If you also plan to do image editing or variations, remember to switch to multipart/form-data and include the appropriate files.
---
*Generated: 2025-08-25T17:36:21.068Z | Response ID: resp_68ac9e95baa481928265fceae0df6fad076fa95d92ed65df | Model: gpt-5 | Time: 127.5s | Iterations: 1 | Input: 0.2k | Output: 8.5k*
