> ## Documentation Index > Fetch the complete documentation index at: https://docs.mage.space/llms.txt > Use this file to discover all available pages before exploring further. # GPT Image 2 > Generate images with GPT Image 2 through the Mage API: the fields of POST /v1/gpt_image_2/generate, its options by model, the rules it enforces, and its gem price. OpenAI's GPT Image 2, GPT Image 2.5 Flare, and GPT Image 2.5 Sunburst, for generation and edits. OpenAI's safety filter applies. | Detail | | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | Type | Image | | Models | `gpt-image-2` (GPT Image 2, default), `gpt-image-2.5-flare` (GPT Image 2.5 Flare), `gpt-image-2.5-sunburst` (GPT Image 2.5 Sunburst) | | Image inputs | `image` (reference image), `additional_images` (additional reference images) | | Video inputs | None | | Gems | 9 at the default settings | | Model page | [GPT Image 2](/models/gpt-image-2) | ## Rules A request that breaks one of these is refused with `400 invalid_config` before any gems are charged. * Each model offers some `quality` levels only; a level the chosen model does not offer is refused. Every field below that you leave out keeps its default. Option values are the raw tokens listed per field; a numeric token may be sent as a number. Fields the schema does not list pass through to the model unchanged. The exact charge for other settings is in the response's `billing.gems_charged`, and the balance at [`GET /v1/account`](/api/endpoints/get-account). ## OpenAPI ````yaml api/openapi.json POST /v1/gpt_image_2/generate openapi: 3.1.0 info: title: Mage API version: v1 description: >- Run Mage models from your own code: submit a generation, poll its status, download the result. Every request is paid in gems. contact: name: Mage url: https://www.mage.space email: mage@mage.space servers: - url: https://api.mage.space description: Production security: - apiKey: [] tags: - name: Requests description: Submit, poll, and cancel generations. - name: Catalog description: What the API can generate with. - name: Account description: The gems balance. - name: Uploads description: Large input files. - name: Image models description: One endpoint per image architecture. - name: Video models description: One endpoint per video architecture. paths: /v1/gpt_image_2/generate: post: tags: - Image models summary: GPT Image 2 description: Generate an image with GPT Image 2. operationId: generate_gpt_image_2 parameters: - name: Idempotency-Key in: header required: false description: >- A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key. schema: type: string minLength: 1 maxLength: 255 requestBody: required: true description: A partial config for GPT Image 2. content: application/json: schema: type: object properties: prompt: type: string minLength: 1 description: The text prompt. seed: description: >- Integer seed for reproducible output; omit or send null for a random seed. anyOf: - type: integer - type: 'null' model_id: type: string enum: - gpt-image-2 - gpt-image-2.5-flare - gpt-image-2.5-sunburst description: The model variant to generate with. default: gpt-image-2 aspect_ratio: type: string enum: - ultrawide - cinema - landscape - computer - square - portrait - tablet - phone - ultratall description: Aspect ratio token. default: portrait resolution: type: string enum: - 1K - 2K description: Output resolution token. default: 1K image: anyOf: - type: string format: uri - type: string pattern: ^data:[^;,]+(?:;[^;,]+)*;base64, description: The reference image. An https URL or a data URL. additional_images: type: array items: anyOf: - type: string format: uri - type: string pattern: ^data:[^;,]+(?:;[^;,]+)*;base64, description: >- Additional reference images. Each an https URL or a data URL. quality: type: string default: low required: - prompt additionalProperties: true example: prompt: Editorial portrait in soft daylight, 35mm film look aspect_ratio: portrait responses: '202': description: >- The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing. content: application/json: schema: $ref: '#/components/schemas/Request' example: request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff status: in_progress architecture: gpt_image_2 model_id: gpt-image-2 created_at: '2026-09-17T14:52:48.000Z' updated_at: '2026-09-17T14:52:49.000Z' billing: mode: gems gems_charged: 9 result: null error: null status_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status cancel_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel '400': $ref: '#/components/responses/InvalidGenerateRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientGems' '403': $ref: '#/components/responses/GenerationForbidden' '410': $ref: '#/components/responses/ArchitectureRetired' '429': $ref: '#/components/responses/TooManyRequests' '451': $ref: '#/components/responses/ExternalContentBlock' '500': $ref: '#/components/responses/InternalError' components: schemas: Request: type: object properties: request_id: type: string format: uuid description: The request id, also the id in `status_url` and `cancel_url`. status: type: string enum: - queued - in_progress - completed - failed - cancelled description: >- `queued` and `in_progress` are live; `completed`, `failed`, and `cancelled` are final. architecture: type: string description: The architecture the request generates with. model_id: anyOf: - type: string - type: 'null' description: The model variant, when the architecture has variants. created_at: type: string format: date-time description: When the request was accepted. updated_at: type: string format: date-time description: When the request last changed. billing: type: object properties: mode: type: string const: gems description: Every API request is paid in gems. gems_charged: type: number description: Gems debited for the request. gems_refunded: description: Gems returned to the account; present on failed requests. type: number required: - mode - gems_charged additionalProperties: false result: anyOf: - type: object properties: type: type: string enum: - image - video - audio description: The media type of the output. url: type: string format: uri description: Where to download the output. width: type: integer description: Output width in pixels. height: type: integer description: Output height in pixels. seed: type: integer description: The seed the generation ran with. expires_at: anyOf: - type: string format: date-time - type: 'null' description: >- When `url` stops working: 30 days after the request for temporary media, or null for permanent media. moderation: type: object properties: nsfw: type: boolean description: Whether moderation flagged the output as NSFW. required: - nsfw additionalProperties: false description: Moderation flags on the output. required: - type - url - width - height - seed - expires_at - moderation additionalProperties: false - type: 'null' description: The output once `status` is `completed`, else null. error: anyOf: - type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - not_found - insufficient_gems - forbidden - content_blocked - request_finished - too_many_requests - generation_failed - internal_error description: A stable error code. message: type: string description: What went wrong, for a person. required: - code - message additionalProperties: false - type: 'null' description: Why the request failed once `status` is `failed`, else null. status_url: type: string format: uri description: Poll this URL for the request. cancel_url: type: string format: uri description: POST to this URL to stop the request. required: - request_id - status - architecture - model_id - created_at - updated_at - billing - result - error - status_url - cancel_url additionalProperties: false Error: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - not_found - insufficient_gems - forbidden - content_blocked - request_finished - too_many_requests - generation_failed - internal_error description: A stable error code; treat an unknown code by its HTTP status. message: type: string description: What went wrong, for a person. request_id: description: >- The request the refusal belongs to, when one was recorded before the refusal. type: string format: uuid gems_required: description: The price of the refused generation, on `insufficient_gems`. type: number docs_url: description: Where to read the API reference, on `not_found`. type: string format: uri required: - code - message additionalProperties: true description: Further fields depend on the code. required: - error additionalProperties: false responses: InvalidGenerateRequest: description: >- The body is not a JSON object, sets a server-owned field, contradicts the architecture, breaks a field's type or token list, or breaks a model rule; or the `Idempotency-Key` is malformed. `invalid_config` names the field or the rule. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_config message: '`resolution` must be one of: 768P, 2K.' Unauthorized: description: The key is missing, malformed, unknown, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: The API key is invalid or has been revoked. InsufficientGems: description: The gems balance is below the price. `gems_required` is the price. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_gems message: >- This generation costs 40 gems and the account balance is too low. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff gems_required: 40 GenerationForbidden: description: >- The account cannot generate (`forbidden`), or the request was blocked by the content policy before it ran (`content_blocked`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: content_blocked message: The request was blocked by Mage's content policy. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff ArchitectureRetired: description: The architecture has been retired. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: architecture_retired message: This architecture has been retired. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff TooManyRequests: description: >- The account already has its cap of generations in flight (20 unless set otherwise for the account), web and API together. Wait for some to finish. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: too_many_requests message: >- At most 20 generations may be in flight at once for this account; 20 are running now. ExternalContentBlock: description: The request was blocked by an external content restriction. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: content_blocked message: The request was blocked by an external content restriction. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff InternalError: description: >- Something failed on Mage's side. Retry, and contact support if it persists. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: >- Something went wrong on our side. Retry, and contact support if it persists. securitySchemes: apiKey: type: http scheme: bearer description: >- An API key from Settings → API, sent as `Authorization: Bearer mage_sk_…`. Keys are for server-side code only. ````