diff --git a/.vitepress/theme/OfficialNativeApiSidebar.vue b/.vitepress/theme/OfficialNativeApiSidebar.vue index 9c139d88..b1589083 100644 --- a/.vitepress/theme/OfficialNativeApiSidebar.vue +++ b/.vitepress/theme/OfficialNativeApiSidebar.vue @@ -25,6 +25,14 @@ const models = [ ] const openaiModels = [ + { + text: 'GPT Image 2.5 Flare', + link: '/model-api-reference/official-native-api/openai/gpt-image-2.5-flare', + }, + { + text: 'GPT Image 2.5 Sunburst', + link: '/model-api-reference/official-native-api/openai/gpt-image-2.5-sunburst', + }, { text: 'GPT Image 2', link: '/model-api-reference/official-native-api/openai/gpt-image-2', diff --git a/model-api-reference/official-native-api/index.md b/model-api-reference/official-native-api/index.md index a622e1bd..562915eb 100644 --- a/model-api-reference/official-native-api/index.md +++ b/model-api-reference/official-native-api/index.md @@ -12,9 +12,11 @@ section. ## OpenAI +- [GPT Image 2.5 Flare](/model-api-reference/official-native-api/openai/gpt-image-2.5-flare) +- [GPT Image 2.5 Sunburst](/model-api-reference/official-native-api/openai/gpt-image-2.5-sunburst) - [GPT Image 2](/model-api-reference/official-native-api/openai/gpt-image-2) -GPT Image 2 uses the native OpenAI Images API at `/v1/images/generations`. Pass `gpt-image-2` as the model value and use the synchronous response directly; this is separate from the general `/v1/run` model endpoint. +GPT Image models use the native OpenAI Images API at `/v1/images/generations` and `/v1/images/edits`. Pass the exact public model value shown on each page and use the synchronous response directly; these endpoints are separate from the general `/v1/run` model endpoint. Choose Flare for faster everyday creative work and Sunburst when visual fidelity and precision take priority. ## ByteDance diff --git a/model-api-reference/official-native-api/openai/gpt-image-2.5-flare.md b/model-api-reference/official-native-api/openai/gpt-image-2.5-flare.md new file mode 100644 index 00000000..24d98c85 --- /dev/null +++ b/model-api-reference/official-native-api/openai/gpt-image-2.5-flare.md @@ -0,0 +1,85 @@ +--- +title: GPT Image 2.5 Flare Native API Reference +description: Generate and edit images with GPT Image 2.5 Flare through SandBase's native OpenAI Images API. +aside: false +outline: false +apiReference: + title: GPT Image 2.5 Flare + operation: OpenAI Images + method: POST + path: /v1/images/generations + description: Generate images with the provider-compatible OpenAI Images API. This synchronous endpoint returns image data directly. + signature: client.images.generate(params) + groups: + - title: Request body + schema: ImageGenerateParams + description: Use the native OpenAI Images request shape. The model must be gpt-image-2.5-flare. + fields: + - { name: model, type: string, required: true, description: Use gpt-image-2.5-flare on this endpoint., default: gpt-image-2.5-flare } + - { name: prompt, type: string, required: true, description: Text description of the image to generate. } + - { name: n, type: integer, required: false, description: Number of images to generate when supported. } + - { name: size, type: string, required: false, description: Output dimensions supported by the model. } + - { name: quality, type: string, required: false, description: Output quality such as low, medium, high, or auto. } + - { name: background, type: string, required: false, description: Background setting such as transparent, opaque, or auto. } + - { name: output_format, type: string, required: false, description: Output encoding such as png, webp, or jpeg. } + - { name: output_compression, type: integer, required: false, description: Output compression level from 0 to 100. } + - { name: moderation, type: string, required: false, description: Provider-compatible moderation setting. } + - { name: user, type: string, required: false, description: Provider-compatible end-user identifier. } + examples: + - label: cURL + language: bash + code: |- + curl https://api.sandbase.ai/v1/images/generations \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model":"gpt-image-2.5-flare","prompt":"A paper-cut city floating above the clouds","size":"1024x1024"}' + - label: Python + language: python + code: |- + from openai import OpenAI + + client = OpenAI(api_key="sk-...", base_url="https://api.sandbase.ai/v1") + result = client.images.generate( + model="gpt-image-2.5-flare", + prompt="A paper-cut city floating above the clouds", + size="1024x1024", + ) + print(result.data[0].b64_json or result.data[0].url) + response: + status: 200 OK + code: |- + { + "created": 1787529600, + "data": [{"b64_json": "iVBORw0KGgo..."}], + "usage": {"input_tokens": 12, "output_tokens": 4096, "total_tokens": 4108} + } +--- + + + +## Native protocol notes + +GPT Image 2.5 Flare is optimized for fast, high-quality image generation and editing in everyday creative workflows. It uses the OpenAI Images API contract, not the general SandBase `/v1/run` model endpoint. Requests are synchronous and return image data in `data` as `b64_json` or a URL. + +Use the shared [image generation reference](/api-reference/images/generations) for authentication, response details, limits, and error handling. The SandBase native catalog entries are `openai/gpt-image-2.5-flare-official` and `openai/gpt-image-2.5-flare-official/edit`; send the public model name `gpt-image-2.5-flare` in native requests. + +## Edit images + +Send edits to `POST /v1/images/edits` as `multipart/form-data`. Provide `model`, `prompt`, and at least one `image` file. Repeat the `image` field to compose or edit multiple source images. + +```bash +curl https://api.sandbase.ai/v1/images/edits \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -F "model=gpt-image-2.5-flare" \ + -F "prompt=Turn this product photo into a warm editorial scene" \ + -F "image=@product.png" \ + -F "quality=high" +``` + +See the shared [image editing reference](/api-reference/images/edits) for the multipart request and response schema. To use the general asynchronous `/v1/run` contract instead, see [`openai/gpt-image-2.5-flare/edit`](https://www.sandbase.ai/model/openai/gpt-image-2.5-flare/edit). + +## Official OpenAI resources + +- [Images API guide](https://platform.openai.com/docs/guides/images) +- [Images API reference](https://platform.openai.com/docs/api-reference/images) +- [OpenAI API quickstart](https://platform.openai.com/docs/quickstart) diff --git a/model-api-reference/official-native-api/openai/gpt-image-2.5-sunburst.md b/model-api-reference/official-native-api/openai/gpt-image-2.5-sunburst.md new file mode 100644 index 00000000..29228e76 --- /dev/null +++ b/model-api-reference/official-native-api/openai/gpt-image-2.5-sunburst.md @@ -0,0 +1,85 @@ +--- +title: GPT Image 2.5 Sunburst Native API Reference +description: Generate and edit images with GPT Image 2.5 Sunburst through SandBase's native OpenAI Images API. +aside: false +outline: false +apiReference: + title: GPT Image 2.5 Sunburst + operation: OpenAI Images + method: POST + path: /v1/images/generations + description: Generate images with the provider-compatible OpenAI Images API. This synchronous endpoint returns image data directly. + signature: client.images.generate(params) + groups: + - title: Request body + schema: ImageGenerateParams + description: Use the native OpenAI Images request shape. The model must be gpt-image-2.5-sunburst. + fields: + - { name: model, type: string, required: true, description: Use gpt-image-2.5-sunburst on this endpoint., default: gpt-image-2.5-sunburst } + - { name: prompt, type: string, required: true, description: Text description of the image to generate. } + - { name: n, type: integer, required: false, description: Number of images to generate when supported. } + - { name: size, type: string, required: false, description: Output dimensions supported by the model. } + - { name: quality, type: string, required: false, description: Output quality such as low, medium, high, or auto. } + - { name: background, type: string, required: false, description: Background setting such as transparent, opaque, or auto. } + - { name: output_format, type: string, required: false, description: Output encoding such as png, webp, or jpeg. } + - { name: output_compression, type: integer, required: false, description: Output compression level from 0 to 100. } + - { name: moderation, type: string, required: false, description: Provider-compatible moderation setting. } + - { name: user, type: string, required: false, description: Provider-compatible end-user identifier. } + examples: + - label: cURL + language: bash + code: |- + curl https://api.sandbase.ai/v1/images/generations \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model":"gpt-image-2.5-sunburst","prompt":"A cinematic glass pavilion beside a black-sand beach","size":"1536x1024"}' + - label: Python + language: python + code: |- + from openai import OpenAI + + client = OpenAI(api_key="sk-...", base_url="https://api.sandbase.ai/v1") + result = client.images.generate( + model="gpt-image-2.5-sunburst", + prompt="A cinematic glass pavilion beside a black-sand beach", + size="1536x1024", + ) + print(result.data[0].b64_json or result.data[0].url) + response: + status: 200 OK + code: |- + { + "created": 1787529600, + "data": [{"b64_json": "iVBORw0KGgo..."}], + "usage": {"input_tokens": 12, "output_tokens": 4096, "total_tokens": 4108} + } +--- + + + +## Native protocol notes + +GPT Image 2.5 Sunburst prioritizes visual fidelity and precision for complex image generation and editing workflows. It uses the OpenAI Images API contract, not the general SandBase `/v1/run` model endpoint. Requests are synchronous and return image data in `data` as `b64_json` or a URL. + +Use the shared [image generation reference](/api-reference/images/generations) for authentication, response details, limits, and error handling. The SandBase native catalog entries are `openai/gpt-image-2.5-sunburst-official` and `openai/gpt-image-2.5-sunburst-official/edit`; send the public model name `gpt-image-2.5-sunburst` in native requests. + +## Edit images + +Send edits to `POST /v1/images/edits` as `multipart/form-data`. Provide `model`, `prompt`, and at least one `image` file. Repeat the `image` field to compose or edit multiple source images. + +```bash +curl https://api.sandbase.ai/v1/images/edits \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -F "model=gpt-image-2.5-sunburst" \ + -F "prompt=Preserve the subject and replace the background with a precise architectural studio" \ + -F "image=@portrait.png" \ + -F "quality=high" +``` + +See the shared [image editing reference](/api-reference/images/edits) for the multipart request and response schema. To use the general asynchronous `/v1/run` contract instead, see [`openai/gpt-image-2.5-sunburst/edit`](https://www.sandbase.ai/model/openai/gpt-image-2.5-sunburst/edit). + +## Official OpenAI resources + +- [Images API guide](https://platform.openai.com/docs/guides/images) +- [Images API reference](https://platform.openai.com/docs/api-reference/images) +- [OpenAI API quickstart](https://platform.openai.com/docs/quickstart) diff --git a/public/openapi.yaml b/public/openapi.yaml index ac94f9aa..6a1e41b3 100644 --- a/public/openapi.yaml +++ b/public/openapi.yaml @@ -234,9 +234,9 @@ paths: tags: [Images] summary: Generate an image description: >- - Generate images through the synchronous OpenAI Images-compatible endpoint. The public model name is - gpt-image-2. Additional compatible JSON fields are forwarded unchanged. Streaming and asynchronous mode - are not supported on this endpoint. + Generate images through the synchronous OpenAI Images-compatible endpoint. Supported public model names are + gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. Additional compatible JSON fields are forwarded + unchanged. Streaming and asynchronous mode are not supported on this endpoint. requestBody: required: true content: @@ -281,8 +281,9 @@ paths: summary: Edit an image description: >- Edit one or more uploaded images through the synchronous OpenAI Images-compatible multipart endpoint. - Repeating the image field is supported. Additional compatible multipart fields are forwarded unchanged. - Streaming and asynchronous mode are not supported on this endpoint. + Supported public model names are gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. Repeating the + image field is supported. Additional compatible multipart fields are forwarded unchanged. Streaming and + asynchronous mode are not supported on this endpoint. requestBody: required: true content: @@ -4372,7 +4373,7 @@ components: properties: model: type: string - const: gpt-image-2 + enum: [gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst] prompt: type: string minLength: 1 @@ -4381,10 +4382,10 @@ components: minimum: 1 size: type: string - description: Output size supported by gpt-image-2, such as 1024x1024, 1024x1536, 1536x1024, or auto. + description: Output size supported by the selected model, such as 1024x1024, 1024x1536, 1536x1024, or auto. quality: type: string - description: Output quality supported by gpt-image-2, such as low, medium, high, or auto. + description: Output quality supported by the selected model, such as low, medium, high, or auto. background: type: string description: Background setting such as transparent, opaque, or auto. @@ -4416,7 +4417,7 @@ components: properties: model: type: string - const: gpt-image-2 + enum: [gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst] prompt: type: string minLength: 1 diff --git a/scripts/validate-doc-content.mjs b/scripts/validate-doc-content.mjs index e9f57e5c..bf3674ec 100644 --- a/scripts/validate-doc-content.mjs +++ b/scripts/validate-doc-content.mjs @@ -177,6 +177,14 @@ for (const filename of ['gemini-3-pro-image.md', 'gemini-3.1-flash-image.md']) { assert.doesNotMatch(geminiImageReference, /path:\s*\/v1\/chat\/completions/, `${filename} must not advertise Chat Completions`) } +for (const variant of ['flare', 'sunburst']) { + const gptImage25Reference = readFileSync(`model-api-reference/official-native-api/openai/gpt-image-2.5-${variant}.md`, 'utf8') + assert.match(gptImage25Reference, /path:\s*\/v1\/images\/generations/, `GPT Image 2.5 ${variant} must document native generation`) + assert.match(gptImage25Reference, /POST \/v1\/images\/edits/, `GPT Image 2.5 ${variant} must document native editing`) + assert.match(gptImage25Reference, new RegExp(`gpt-image-2\\.5-${variant}`), `GPT Image 2.5 ${variant} must use its exact public alias`) + assert.doesNotMatch(gptImage25Reference, /model=?(?:"|')?openai\/gpt-image-2\.5/, `GPT Image 2.5 ${variant} must not send an internal model name to the native endpoint`) +} + const runReference = readFileSync('api-reference/models/run.md', 'utf8') assert.doesNotMatch(runReference, /webhook_url[^\n]*API tasks/i, 'Run reference must not promise callbacks for API capabilities') assert.match(runReference, /webhook_url[^\n]*image, video, or audio tasks/i, 'Run reference must match webhook capability scope') diff --git a/scripts/validate-public-api-surface.mjs b/scripts/validate-public-api-surface.mjs index 3504597f..7ccaf384 100644 --- a/scripts/validate-public-api-surface.mjs +++ b/scripts/validate-public-api-surface.mjs @@ -541,10 +541,11 @@ assert.match(imageGenerationPath, /application\/json:/, 'Image generation must d const imageEditPath = openapi.match(/^ \/v1\/images\/edits:\n[\s\S]*?(?=^ \/)/m)?.[0] ?? '' assert.match(imageEditPath, /multipart\/form-data:/, 'Image edits must document multipart uploads') const imageGenerationRequest = openapi.match(/^ ImageGenerationRequest:\n[\s\S]*?(?=^ [A-Za-z])/m)?.[0] ?? '' -assert.match(imageGenerationRequest, /const: gpt-image-2/, 'Image generation must publish the implemented public model alias') +assert.match(imageGenerationRequest, /enum: \[gpt-image-2, gpt-image-2\.5-flare, gpt-image-2\.5-sunburst\]/, 'Image generation must publish every implemented public model alias') assert.match(imageGenerationRequest, /additionalProperties: true/, 'Image generation must preserve compatible JSON fields') assert.match(imageGenerationRequest, /stream:\n\s+type: boolean\n\s+const: false/, 'Image generation must not advertise unsupported streaming') const imageEditRequest = openapi.match(/^ ImageEditRequest:\n[\s\S]*?(?=^ [A-Za-z])/m)?.[0] ?? '' +assert.match(imageEditRequest, /enum: \[gpt-image-2, gpt-image-2\.5-flare, gpt-image-2\.5-sunburst\]/, 'Image edits must publish every implemented public model alias') assert.match(imageEditRequest, /required: \[model, prompt, image\]/, 'Image edits must require model, prompt, and source image') assert.match(imageEditRequest, /type: array\n\s+items:\n\s+type: string\n\s+format: binary/, 'Image edits must allow repeated source image files') const imagesResponse = openapi.match(/^ ImagesResponse:\n[\s\S]*?(?=^ [A-Za-z])/m)?.[0] ?? '' @@ -682,6 +683,10 @@ assert.match(officialNativeSidebar, /official-native-api\/google\/gemini-3\.1-fl assert.doesNotMatch(officialNativeSidebar, /llm-models\/google\/gemini-3(?:\.1)?-(?:pro|flash)-image/, 'Official Native API sidebar must use dedicated native pages for Gemini image models') assert.match(officialNativeSidebar, /GPT Image 2/, 'Official Native API sidebar must expose GPT Image 2') assert.match(officialNativeSidebar, /official-native-api\/openai\/gpt-image-2/, 'Official Native API sidebar must link GPT Image 2') +assert.match(officialNativeSidebar, /GPT Image 2\.5 Flare/, 'Official Native API sidebar must expose GPT Image 2.5 Flare') +assert.match(officialNativeSidebar, /official-native-api\/openai\/gpt-image-2\.5-flare/, 'Official Native API sidebar must link GPT Image 2.5 Flare') +assert.match(officialNativeSidebar, /GPT Image 2\.5 Sunburst/, 'Official Native API sidebar must expose GPT Image 2.5 Sunburst') +assert.match(officialNativeSidebar, /official-native-api\/openai\/gpt-image-2\.5-sunburst/, 'Official Native API sidebar must link GPT Image 2.5 Sunburst') const scheduleOverview = readFileSync(new URL('../api-reference/deployments/index.md', import.meta.url), 'utf8') assert.match(scheduleOverview, /POST \/v1\/deployments\/\{deployment_id\}\/runs/, 'Schedule overview must document the preferred plural trigger path') assert.match(scheduleOverview, /POST \/v1\/deployments\/\{deployment_id\}\/run` remains a compatibility alias/, 'Schedule overview must label the singular trigger path as compatibility-only')