# Summary of agent_20250825173621_research-and-provide-the-exact.md
## Purpose
- Provide exact, practical implementation details for calling OpenAI's gpt-image-1 model via the Images API, covering endpoints, request/response formats, headers, examples, and error handling.
## Overall Structure
- Mirrors a 7-point requirements list, followed by a detailed "Full Output" section containing:
1. Endpoint URLs
2. Request body structures (generations, edits, variations)
3. How to handle the size parameter
4. Response structure and URL extraction
5. Headers and authentication
6. Working examples (cURL and JavaScript)
7. Common errors and handling
- Ends with practical tips and a generated metadata line (timestamp, response ID, model, timing).
## Key Points by Section
### 1. Endpoint URLs
- **Text-to-image (prompt-based)**: `POST https://api.openai.com/v1/images/generations`
- **Image edits (with optional mask)**: `POST https://api.openai.com/v1/images/edits`
- **Image variations (from an input image)**: `POST https://api.openai.com/v1/images/variations`
### 2. Request Body Structures
**Generations (application/json)**
- Required: model ("gpt-image-1"), prompt (string)
- Optional: size ("WIDTHxHEIGHT"), n (int, default 1; may be limited to 1), response_format ("url" default or "b64_json"), user (string)
- Notes: Unsupported fields produce "Unrecognized request argument" errors.
**Edits (multipart/form-data)**
- Required: model, image (file), prompt
- Optional: mask (file, transparent areas indicate edit regions), size, n, response_format, user
- Notes: Prefer PNG for transparency; can provide multiple images; mask should match image dimensions.
**Variations (multipart/form-data)**
- Required: model, image (file)
- Optional: size, n, response_format, user
- Notes: Similar handling as edits without prompt/mask requirements.
### 3. Size Parameter Handling
- Location: In the request body (not URL or headers)
- Format: "WIDTHxHEIGHT" (e.g., "256x256", "512x512", "1024x1024")
- Default: "1024x1024" if omitted
- Validity: Common supported sizes listed above; invalid sizes return 400 errors
### 4. Response Structure and Image Extraction
**response_format "url" (default)**
- JSON: `{ "created": <unix>, "data": [ { "url": "https://...", optionally "revised_prompt" } ] }`
- Extract image: `data[0].url`
- URLs are temporary (commonly ~1 hour); download for permanence
**response_format "b64_json"**
- JSON: `{ "created": <unix>, "data": [ { "b64_json": "<base64>" } ] }`
- Decode base64 and save to file (e.g., PNG)
### 5. Headers and Authentication
**Required:**
- Authorization: `Bearer YOUR_OPENAI_API_KEY`
- Content-Type: `application/json` (generations) or `multipart/form-data` (edits/variations)
**Optional:**
- OpenAI-Organization, OpenAI-Project
- No special beta headers required; always use HTTPS
### 6. Working Examples
- cURL: generations with URL response
- cURL: generations with base64 response piped to jq and base64 to save file
- JavaScript fetch (Node/browser): generations with URL response and basic error handling
- JavaScript fetch (Node): generations with base64 response saved to disk
- cURL: image edit with mask using multipart form-data
### 7. Common Errors and Handling
- **400 invalid_request_error**: missing fields, invalid size, unsupported params, disallowed n > 1; validate inputs and adjust
- **401 unauthorized**: missing/invalid API key; ensure proper Authorization header
- **404 not_found**: incorrect model or endpoint; verify names
- **415 unsupported_media_type**: using wrong Content-Type for file endpoints; switch to multipart/form-data
- **422 unprocessable_entity**: corrupted/unsupported images, mask size mismatch; re-encode as PNG and match dimensions
- **429 rate_limit_exceeded/server_overloaded**: backoff and retry
- **500 server_error**: retry with backoff; log; contact support if persistent
- **Safety/content policy errors**: adjust prompts to comply
- Error payload shape: `{ "error": { "message": "...", "type": "...", "param": null, "code": null } }`
## Practical Tips
- Download image promptly when using URL responses due to expiration
- Prefer b64_json when storing binaries directly
- Keep prompts concise yet specific
- For edits, use PNG masks with correct transparency and matching dimensions
## Metadata
Document ends with a generated line including timestamp (2025-08-25T17:36:21.068Z), response ID, model (gpt-5), duration, iterations, and I/O sizes.
---
*Summary generated on 2025-08-25 using GPT-5*
