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

# GPT Image 2 Web API examples

> Copy gpt-image-2-web examples for text-to-image, idempotent asynchronous work, one or multiple reference images, polling, and Base64 output.

## Generate an image synchronously

```bash theme={"system"}
curl 'https://api.yingtu.ai/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_YINGTU_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2-web",
    "prompt": "A compact reading lamp on a pale desk, editorial product photo, no text",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }' > response.json

jq -er '.data[0].b64_json' response.json | base64 --decode > lamp.png
```

`quality` is forwarded; the selected upstream determines its effect.

## Submit and poll an asynchronous generation

```javascript theme={"system"}
const headers = {
  Authorization: `Bearer ${process.env.YINGTU_API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": crypto.randomUUID(),
};

const submitted = await fetch(
  "https://api.yingtu.ai/v1/images/tasks",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "gpt-image-2-web",
      action: "generate",
      prompt: "A glass greenhouse in a snowy forest at dusk, no text",
      size: "2048x2048",
      n: 1,
    }),
  },
);
if (submitted.status !== 202) throw new Error(`Submit failed: ${submitted.status}`);

const { task_id } = await submitted.json();
const deadline = Date.now() + 5 * 60_000;
let image;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://api.yingtu.ai/v1/tasks/${task_id}`,
    { headers: { Authorization: headers.Authorization } },
  );
  if (!response.ok) throw new Error(`Poll failed: ${response.status}`);
  const task = await response.json();
  if (task.status === "completed") {
    image = task.result?.data?.[0]?.b64_json;
    if (!image) throw new Error("Completed task did not include image data");
    break;
  }
  if (["failed", "expired"].includes(task.status)) throw new Error(task.error?.message || task.status);
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
if (!image) throw new Error("Task deadline exceeded");
```

## Edit one source image

```python theme={"system"}
import base64
import os
from pathlib import Path

import requests

with Path("product.png").open("rb") as source:
    response = requests.post(
        "https://api.yingtu.ai/v1/images/edits",
        headers={"Authorization": f"Bearer {os.environ['YINGTU_API_KEY']}"},
        data={
            "model": "gpt-image-2-web",
            "prompt": "Keep the product and replace the background with pale blue",
            "size": "1024x1024",
            "n": "1",
        },
        files={"image": ("product.png", source, "image/png")},
        timeout=180,
    )

response.raise_for_status()
body = response.json()
items = body.get("data") or []
encoded = items[0].get("b64_json") if items else None
if not encoded:
    raise RuntimeError("Response did not include image data")
Path("edited.png").write_bytes(base64.b64decode(encoded))
```

## Queue a multi-image edit with JSON

```javascript theme={"system"}
import fs from "node:fs";

const product = fs.readFileSync("product.png").toString("base64");
const setting = fs.readFileSync("setting.jpg").toString("base64");
const submitted = await fetch("https://api.yingtu.ai/v1/images/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YINGTU_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: "gpt-image-2-web",
    action: "edit",
    prompt: "Keep the product and replace the background with pale blue",
    input_images: [
      { mime_type: "image/png", data: product },
      { mime_type: "image/jpeg", data: setting },
    ],
    size: "1024x1024",
    quality: "high",
    n: 1,
  }),
});
if (submitted.status !== 202) throw new Error(`Submit failed: ${submitted.status}`);
const { task_id } = await submitted.json();
console.log(task_id);
```

Each decoded source must not exceed 20 MiB and all source images together must remain within 64 MiB. Poll the returned task with the bounded loop above; successful output remains available for 24 hours.

## Test this model online

The embedded operation fixes `gpt-image-2-web` and exposes the three documented sizes plus forwarded quality values.

<Warning>
  Try it sends a real USD 0.03 request at the current price. Use a development key and do not share generated cURL that contains it.
</Warning>


## OpenAPI

````yaml openapi-models/gpt-image-2-web.json POST /v1/images/generations
openapi: 3.1.0
info:
  title: gpt-image-2-web API
  version: 1.0.0
  description: Model-fixed GPT Image generation for gpt-image-2-web.
servers:
  - url: https://api.yingtu.ai
    description: YingTu API
security: []
tags:
  - name: Synchronous generation
    description: Wait for a complete Gemini response in one HTTP request.
  - name: Asynchronous tasks
    description: >-
      Submit image work, then retrieve the task until it reaches a terminal
      state.
  - name: GPT Image generation
    description: >-
      Generate GPT Image output synchronously or submit a YingTu task-ID
      generation request.
  - name: GPT Image editing
    description: Edit one source image synchronously with GPT Image.
paths:
  /v1/images/generations:
    post:
      tags:
        - GPT Image generation
      summary: 'Billable request: generate an image with gpt-image-2-web'
      description: >-
        This sends a real, billable request with the fixed YingTu model ID
        gpt-image-2-web. Check the current fixed price at
        https://api.yingtu.ai/pricing before sending.
      operationId: generateGptImage_gpt_image_2_web
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAIImageGenerationRequest'
            examples:
              fixedModel:
                summary: Generate with gpt-image-2-web
                value:
                  model: gpt-image-2-web
                  prompt: >-
                    A blue ceramic teapot on a pale table, soft studio light, no
                    text.
                  size: 1024x1024
                  quality: low
                  'n': 1
      responses:
        '200':
          description: Complete GPT Image response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIImagesResponse'
              example:
                created: 1788307200
                data:
                  - b64_json: iVBORw0KGgo=
                usage:
                  input_tokens: 24
                  output_tokens: 1756
                  total_tokens: 1780
                  input_tokens_details:
                    text_tokens: 24
                    image_tokens: 0
                  output_tokens_details:
                    text_tokens: 0
                    image_tokens: 1756
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    OpenAIImageGenerationRequest:
      title: GPT Image generation request
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          $ref: '#/components/schemas/OpenAIImageModelId'
        prompt:
          title: Prompt
          type: string
          minLength: 1
          example: A blue ceramic teapot on a pale table, no text
        size:
          $ref: '#/components/schemas/OpenAIImageSize'
        quality:
          $ref: '#/components/schemas/OpenAIImageQuality'
        'n':
          title: Number of images
          type: integer
          enum:
            - 1
          default: 1
          description: The documented subset returns one image.
    OpenAIImagesResponse:
      title: GPT Image response
      type: object
      required:
        - created
        - data
      properties:
        created:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        data:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/OpenAIImageData'
        size:
          type: string
          description: Output size when returned by the selected GPT Image route.
        quality:
          type: string
          description: Quality value reported by the selected GPT Image route.
        usage:
          $ref: '#/components/schemas/OpenAIImageUsage'
    OpenAIImageModelId:
      title: GPT Image model ID
      type: string
      enum:
        - gpt-image-2-web
      example: gpt-image-2-web
    OpenAIImageSize:
      title: Output size
      type: string
      enum:
        - 1024x1024
        - 2048x2048
        - 3840x2160
      example: 1024x1024
      description: >-
        Current public presets. Set size explicitly for predictable dimensions;
        the 4K landscape value is 3840x2160.
      x-default: 1024x1024
    OpenAIImageQuality:
      title: Image quality
      type: string
      enum:
        - low
        - medium
        - high
        - auto
      example: low
      description: >-
        Forwarded for both GPT Image routes. The selected upstream determines
        how the requested value affects the result.
      x-default: low
    OpenAIImageData:
      type: object
      required:
        - b64_json
      properties:
        b64_json:
          type: string
          format: byte
          description: Base64-encoded image bytes without a data URL prefix.
          example: iVBORw0KGgo=
    OpenAIImageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        total_tokens:
          type: integer
          minimum: 0
        input_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
        output_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    OpenAIImageTokenDetails:
      type: object
      properties:
        text_tokens:
          type: integer
          minimum: 0
        image_tokens:
          type: integer
          minimum: 0
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
        type:
          type: string
          example: invalid_request_error
        param:
          type:
            - string
            - 'null'
        code:
          type:
            - string
            - 'null'
          example: insufficient_user_quota
  responses:
    BadRequest:
      description: Invalid model, field, or parameter value
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid YingTu API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The key is valid but the account lacks balance or access for this
        request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: Insufficient balance for this request
              type: new_api_error
              param: ''
              code: insufficient_user_quota
    RateLimited:
      description: >-
        The selected upstream provider returned a rate, quota, spend, or
        model-capacity limit. For the documented Nano Banana routes, this is the
        official upstream provider and the gateway does not apply a fixed
        platform-side RPM cap. No separate GPT Image gateway RPM or availability
        objective is currently published.
      headers:
        Retry-After:
          description: Seconds to wait before retrying when supplied.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: The request could not be completed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: YingTu API key.

````