{ "openapi": "3.1.0", "info": { "title": "Images API", "version": "1.0.0", "description": "Create images through the OpenAI-compatible CometAPI image generation route. Request parameters vary by model. For the latest model-specific controls, refer to the OpenAI image generation guide: https://developers.openai.com/api/docs/guides/image-generation" }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Use your CometAPI key." } } }, "paths": { "/v1/images/generations": { "post": { "summary": "Create images", "operationId": "images", "description": "Generate images from a text prompt using OpenAI-compatible request shapes on CometAPI. For the latest model-specific output controls and parameter support, refer to the OpenAI image generation guide: https://developers.openai.com/api/docs/guides/image-generation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "The image generation model to use. Choose a current model from the [Models page](/overview/models).", "default": "gpt-image-2" }, "prompt": { "type": "string", "description": "Text description of the image you want to generate.", "example": "A paper boat floating on calm water at sunrise." }, "n": { "type": "integer", "description": "Number of images to generate. Keep this at 1 for the broadest compatibility.", "default": 1 }, "quality": { "type": "string", "description": "Quality setting for models that support it. GPT image models accept `low`, `medium`, `high`, and `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` also accept `xhigh` and `max`. `dall-e-3` accepts `standard` and `hd`. See the OpenAI image generation guide for the latest model-specific values.", "example": "low" }, "background": { "type": "string", "description": "Background mode for the generated image. Set `transparent` to generate an isolated subject with no background fill; this requires `output_format` set to `png` or `webp`, and returns an error with `jpeg`. Set `opaque` for a solid background, or `auto` to let the model decide. Supported on `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`.", "enum": [ "transparent", "opaque", "auto" ] }, "output_compression": { "type": "integer", "description": "Compression level for the output image, from 0 to 100. Applies when `output_format` is `webp` or `jpeg`. Lower values produce smaller files with more compression artifacts.", "minimum": 0, "maximum": 100, "default": 100 }, "moderation": { "type": "string", "description": "Content moderation level for GPT image models. `low` is less restrictive; `auto` is the default.", "enum": [ "low", "auto" ], "default": "auto" }, "partial_images": { "type": "integer", "description": "Number of partial images to emit while a streaming response is in progress, from 0 to 3. Each partial image arrives as an `image_generation.partial_image` event before the final `image_generation.completed` event. Applies when `stream` is `true`.", "minimum": 0, "maximum": 3 }, "size": { "type": "string", "description": "Requested output size. Supported values depend on the selected model. See the OpenAI image generation guide for the latest model-specific ranges.", "example": "1024x1024" }, "response_format": { "type": "string", "description": "The response container for `dall-e-2` and `dall-e-3`. This parameter is not supported for GPT image models, which return base64-encoded image data.", "enum": [ "url", "b64_json" ] }, "output_format": { "type": "string", "description": "The encoded image type for GPT image model results, such as `png`, `jpeg`, or `webp`. See the OpenAI image generation guide for current GPT image output controls.", "example": "jpeg" }, "stream": { "type": "boolean", "description": "Set this to `true` to receive server-sent image generation events instead of waiting for the completed JSON response. Streaming responses use `text/event-stream` and can include final events such as `image_generation.completed`. When `stream` and `async` are both `true`, async task mode takes precedence and the create request returns JSON instead of a streaming image response.", "default": false }, "async": { "type": "boolean", "description": "CometAPI asynchronous task mode. Set this to `true` to return immediately with `data.task_id`, then poll `GET /v1/images/generations/{task_id}` for the final image data. Documented model IDs for this mode: `gpt-image-2` and `doubao-seedream-4-0-250828`. This is a CometAPI extension, not an OpenAI parameter. When `async` and `stream` are both `true`, async takes precedence and returns JSON task metadata instead of an SSE stream.", "default": false } }, "default": { "model": "gpt-image-2", "prompt": "A paper boat floating on calm water at sunrise.", "n": 1, "size": "1024x1024", "output_format": "jpeg" } }, "examples": { "gpt_image": { "summary": "GPT image generation (gpt-image-2)", "value": { "model": "gpt-image-2", "prompt": "A paper boat floating on calm water at sunrise.", "quality": "low", "size": "1024x1024", "output_format": "jpeg" } }, "transparent_background": { "summary": "Transparent background (gpt-image-2.5-sunburst)", "value": { "model": "gpt-image-2.5-sunburst", "prompt": "A single red apple, centered, isolated subject.", "quality": "low", "size": "1024x1024", "background": "transparent", "output_format": "png" } }, "streaming_image": { "summary": "Streaming image generation", "value": { "model": "gpt-image-2", "prompt": "A paper boat floating on calm water at sunrise.", "quality": "low", "size": "1024x1024", "output_format": "jpeg", "stream": true } }, "async_image": { "summary": "Async image generation", "value": { "model": "gpt-image-2", "prompt": "A paper boat floating on calm water at sunrise.", "quality": "low", "size": "1024x1024", "output_format": "jpeg", "async": true } }, "gpt_image_1": { "summary": "GPT image generation (gpt-image-1)", "value": { "model": "gpt-image-1", "prompt": "A paper boat floating on calm water at sunrise.", "quality": "low", "size": "1024x1024" } } } } } }, "responses": { "200": { "description": "Image generation result. Synchronous requests return completed image data. Async requests return a task response with `data.task_id`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Completed image response", "required": [ "created", "data" ], "properties": { "created": { "type": "integer", "description": "Unix timestamp for the completed generation." }, "background": { "type": "string", "description": "Background mode returned by models that expose it." }, "output_format": { "type": "string", "description": "Encoded image type returned by GPT image models." }, "quality": { "type": "string", "description": "Quality level returned by models that expose it." }, "size": { "type": "string", "description": "Output size returned by models that expose it." }, "usage": { "type": "object", "description": "Token usage details when returned by the selected model.", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer" }, "text_tokens": { "type": "integer" } } }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer" }, "text_tokens": { "type": "integer" } } } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Temporary image URL when the selected model supports URL output." }, "b64_json": { "type": "string", "description": "Base64-encoded image payload for models that return inline content." }, "revised_prompt": { "type": "string", "description": "Provider-rewritten prompt, when available." } } } } } }, { "type": "object", "title": "Async task response", "required": [ "code", "data" ], "properties": { "code": { "type": "string", "description": "Request status code. A successful async submit returns `success`.", "example": "success" }, "message": { "type": "string", "description": "Optional status message." }, "data": { "type": "object", "required": [ "task_id", "status", "data" ], "properties": { "task_id": { "type": "string", "description": "Task ID to pass to `GET /v1/images/generations/{task_id}`." }, "status": { "type": "string", "description": "Task state for the submitted image generation job.", "enum": [ "pending", "success", "failure" ] }, "data": { "type": "array", "description": "Empty at submit time. Poll the task endpoint to receive final image data.", "items": { "type": "object" } } } } }, "example": { "code": "success", "message": "", "data": { "task_id": "", "status": "pending", "data": [] } } } ] }, "example": { "created": 1781075000, "background": "opaque", "output_format": "jpeg", "quality": "low", "size": "1024x1024", "usage": { "input_tokens": 13, "input_tokens_details": { "image_tokens": 0, "text_tokens": 13 }, "output_tokens": 196, "output_tokens_details": { "image_tokens": 196, "text_tokens": 0 }, "total_tokens": 209 }, "data": [ { "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD..." } ] } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events returned when `stream` is `true`. Events can include image generation progress and final image data." }, "example": "event: image_generation.completed\ndata: {\"created_at\":1783305600,\"type\":\"image_generation.completed\",\"b64_json\":\"\"}\n\n" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "Default", "source": "curl https://api.cometapi.com/v1/images/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A paper boat floating on calm water at sunrise.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"output_format\": \"jpeg\"\n }'\n" }, { "lang": "Python", "label": "Default", "source": "import base64\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n base_url=\"https://api.cometapi.com/v1\",\n api_key=os.environ[\"COMETAPI_KEY\"],\n)\n\nresult = client.images.generate(\n model=\"gpt-image-2\",\n prompt=\"A paper boat floating on calm water at sunrise.\",\n quality=\"low\",\n size=\"1024x1024\",\n output_format=\"jpeg\",\n)\n\nimage_bytes = base64.b64decode(result.data[0].b64_json)\nwith open(\"boat.jpg\", \"wb\") as f:\n f.write(image_bytes)\n" }, { "lang": "JavaScript", "label": "Default", "source": "import fs from \"node:fs\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n baseURL: \"https://api.cometapi.com/v1\",\n apiKey: process.env.COMETAPI_KEY,\n});\n\nconst result = await client.images.generate({\n model: \"gpt-image-2\",\n prompt: \"A paper boat floating on calm water at sunrise.\",\n quality: \"low\",\n size: \"1024x1024\",\n output_format: \"jpeg\",\n});\n\nfs.writeFileSync(\"boat.jpg\", Buffer.from(result.data[0].b64_json, \"base64\"));\n" }, { "lang": "Shell", "label": "Transparent background", "source": "curl https://api.cometapi.com/v1/images/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-image-2.5-sunburst\",\n \"prompt\": \"A single red apple, centered, isolated subject.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"background\": \"transparent\",\n \"output_format\": \"png\"\n }' | jq -r '.data[0].b64_json' | base64 --decode > apple.png" }, { "lang": "Python", "label": "Transparent background", "source": "import base64\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n base_url=\"https://api.cometapi.com/v1\",\n api_key=os.environ[\"COMETAPI_KEY\"],\n)\n\nresult = client.images.generate(\n model=\"gpt-image-2.5-sunburst\",\n prompt=\"A single red apple, centered, isolated subject.\",\n quality=\"low\",\n size=\"1024x1024\",\n background=\"transparent\",\n output_format=\"png\",\n)\n\nimage_bytes = base64.b64decode(result.data[0].b64_json)\nwith open(\"apple.png\", \"wb\") as f:\n f.write(image_bytes)" }, { "lang": "JavaScript", "label": "Transparent background", "source": "import fs from \"node:fs\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n baseURL: \"https://api.cometapi.com/v1\",\n apiKey: process.env.COMETAPI_KEY,\n});\n\nconst result = await client.images.generate({\n model: \"gpt-image-2.5-sunburst\",\n prompt: \"A single red apple, centered, isolated subject.\",\n quality: \"low\",\n size: \"1024x1024\",\n background: \"transparent\",\n output_format: \"png\",\n});\n\nfs.writeFileSync(\"apple.png\", Buffer.from(result.data[0].b64_json, \"base64\"));" }, { "lang": "Shell", "label": "Streaming request", "source": "curl -N https://api.cometapi.com/v1/images/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A paper boat floating on calm water at sunrise.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"output_format\": \"jpeg\",\n \"stream\": true\n }'\n" }, { "lang": "Python", "label": "Streaming request", "source": "import json\nimport os\nimport urllib.request\n\npayload = {\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A paper boat floating on calm water at sunrise.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"output_format\": \"jpeg\",\n \"stream\": True,\n}\n\nrequest = urllib.request.Request(\n \"https://api.cometapi.com/v1/images/generations\",\n data=json.dumps(payload).encode(\"utf-8\"),\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n method=\"POST\",\n)\n\nwith urllib.request.urlopen(request) as response:\n for raw_line in response:\n line = raw_line.decode(\"utf-8\").strip()\n if line:\n print(line)\n" }, { "lang": "JavaScript", "label": "Streaming request", "source": "const response = await fetch(\"https://api.cometapi.com/v1/images/generations\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: \"gpt-image-2\",\n prompt: \"A paper boat floating on calm water at sunrise.\",\n quality: \"low\",\n size: \"1024x1024\",\n output_format: \"jpeg\",\n stream: true,\n }),\n});\n\nconst decoder = new TextDecoder();\nfor await (const chunk of response.body) {\n process.stdout.write(decoder.decode(chunk));\n}\n" }, { "lang": "Shell", "label": "Async request", "source": "curl https://api.cometapi.com/v1/images/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A paper boat floating on calm water at sunrise.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"output_format\": \"jpeg\",\n \"async\": true\n }'\n" }, { "lang": "Python", "label": "Async request", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.cometapi.com/v1/images/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json={\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A paper boat floating on calm water at sunrise.\",\n \"quality\": \"low\",\n \"size\": \"1024x1024\",\n \"output_format\": \"jpeg\",\n \"async\": True,\n },\n)\n\nresult = response.json()\nprint(result[\"data\"][\"task_id\"])\n" }, { "lang": "JavaScript", "label": "Async request", "source": "const response = await fetch(\"https://api.cometapi.com/v1/images/generations\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: \"gpt-image-2\",\n prompt: \"A paper boat floating on calm water at sunrise.\",\n quality: \"low\",\n size: \"1024x1024\",\n output_format: \"jpeg\",\n async: true,\n }),\n});\n\nconst result = await response.json();\nconsole.log(result.data.task_id);\n" } ] } } } }