feat:Update OpenAPI spec with enhanced docs, examples, and schema changes #76
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughThe OpenAPI specification for the Ideogram API was updated to enhance documentation and examples. Several legacy endpoints were marked as such in their summaries. Rich example requests, responses, and code samples were added for multiple endpoints. Schema changes include removal of a property, an enum value addition, and a default value update. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
Note over Client,API: Example flow for /v1/ideogram-v3/generate endpoint
Client->>API: POST /v1/ideogram-v3/generate (with prompt, style_type, etc.)
API-->>Client: JSON response with generated image data
Poem
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
src/libs/Ideogram/openapi.yaml (1)
39-42: Inconsistent x-fern-examples structure for/describe
The newx-fern-examplesblock for/describeincludes only code samples. It would improve clarity and consistency if you also provide explicitrequestandresponseexamples (as seen in other endpoints), so users can see complete input and output schemas.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (19)
src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostEditImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostGenerateImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostGenerateImageV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostReframeImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostRemixImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.GenerateClient.PostRemixImageV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostEditImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostGenerateImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostGenerateImageV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostReframeImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostRemixImage.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IGenerateClient.PostRemixImageV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.GenerateImageRequest.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.GenerateImageRequestV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.ImageGenerationObjectV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.RemixImageRequestV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.StyleType.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.StyleTypeV3.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/JsonSerializerContextTypes.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Ideogram/openapi.yaml(12 hunks)
🔇 Additional comments (8)
src/libs/Ideogram/openapi.yaml (8)
48-48: Legacy suffix appended to/editsummary
The summaryEdit (legacy)correctly indicates this endpoint is deprecated in favor of newer versions.
99-99: Legacy suffix appended to/generatesummary
Good use of(legacy)to flag the old/generateendpoint.
425-425: Legacy suffix appended to/reframesummary
The summary update toReframe (legacy)is consistent with the deprecation strategy.
460-460: Legacy suffix appended to/remixsummary
Marking/remixas legacy is clear and aligns with the other endpoints.
531-553: Comprehensive examples for/upscale
Thex-fern-examplesblock here provides well-structuredrequest,response, andcode-samplessections, which enhances usability.
715-734: Validate/v1/ideogram-v3/reframeexamples
The examples for/v1/ideogram-v3/reframecorrectly includeresolutionand file uploads, and the code samples match the spec.
1936-1936: NewCUSTOMstyle type added toStyleTypeenum
AddingCUSTOMexpands flexibility, but please verify backend support and update any client-side mappings or validation logic to handle this new value.
2171-2171: Default forStyleTypeV3changed fromAUTOtoGENERAL
Ensure that server-side defaults and client SDKs are aligned with this new default, and update any generated docs or tests accordingly.
Comment on lines
+592
to
+611
| x-fern-examples: | ||
| - request: | ||
| prompt: A photo of a cat wearing a hat. | ||
| response: | ||
| body: | ||
| created: '2000-01-23T04:56:07.0000000+00:00' | ||
| data: | ||
| - prompt: A photo of a cat wearing a hat. | ||
| resolution: 1024x1024 | ||
| is_image_safe: true | ||
| seed: 12345 | ||
| url: https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89 | ||
| style_type: GENERAL | ||
| code-samples: | ||
| - sdk: curl | ||
| code: "curl -X POST https://api.ideogram.ai/v1/ideogram-v3/edit \\\n -H \"Api-Key: <apiKey>\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F image=@<file1> \\\n -F mask=@<file1> \\\n -F prompt=\"A photo of a cat wearing a hat.\" \\\n -F rendering_speed=\"DEFAULT\"\n" | ||
| - sdk: python | ||
| code: "import requests\n\nresponse = requests.post(\n \"https://api.ideogram.ai/v1/ideogram-v3/edit\",\n headers={\n \"Api-Key\": \"<apiKey>\"\n },\n data={\n \"prompt\": \"A photo of a cat wearing a hat.\",\n \"rendering_speed\": \"DEFAULT\"\n },\n files={\n \"image\": open(\"<file1>\", \"rb\"),\n \"mask\": open(\"<file1>\", \"rb\"),\n }\n)\nprint(response.json())\nwith open('output.png', 'wb') as f:\n f.write(requests.get(response.json()['data'][0]['url']).content)\n" | ||
| - sdk: typescript | ||
| code: "const formData = new FormData();\nformData.append('prompt', 'A photo of a cat');\nformData.append('rendering_speed', 'TURBO');\nconst response = await fetch('https://api.ideogram.ai/v1/ideogram-v3/edit', {\n method: 'POST',\n headers: { 'Api-Key': '<apiKey>' },\n body: formData\n});\nconst data = await response.json();\nconsole.log(data);\n" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Include file fields in /v1/ideogram-v3/edit request example
The request example lists only prompt, but the curl and SDK samples attach image and mask files as required by the spec. Update the example to include both binary fields:
x-fern-examples:
- request:
prompt: A photo of a cat wearing a hat.
rendering_speed: DEFAULT
image: <binary file>
mask: <binary file>🤖 Prompt for AI Agents (early access)
In src/libs/Ideogram/openapi.yaml between lines 592 and 611, the request example under x-fern-examples for the /v1/ideogram-v3/edit endpoint only includes the prompt field, but the curl and SDK code samples show that image and mask binary files are also required. Update the request example to add the image and mask fields as placeholders for binary files, and include the rendering_speed field to match the samples, ensuring the example accurately reflects the required multipart form data inputs.
Comment on lines
+774
to
+794
| x-fern-examples: | ||
| - request: | ||
| prompt: A photo of a cat | ||
| rendering_speed: DEFAULT | ||
| image_weight: 50 | ||
| aspect_ratio: 1x2 | ||
| response: | ||
| body: | ||
| created: '2000-01-23T04:56:07.0000000+00:00' | ||
| data: | ||
| - prompt: A photo of a cat | ||
| resolution: 1280x800 | ||
| is_image_safe: true | ||
| seed: 12345 | ||
| url: https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89 | ||
| style_type: GENERAL | ||
| code-samples: | ||
| - sdk: curl | ||
| code: "curl -X POST https://api.ideogram.ai/v1/ideogram-v3/remix \\\n -H \"Api-Key: <apiKey>\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F image=@<file1> \\\n -F prompt=\"A photo of a cat\" \\\n -F rendering_speed=\"TURBO\"\n" | ||
| - sdk: python | ||
| code: "import requests\n\nresponse = requests.post(\n \"https://api.ideogram.ai/v1/ideogram-v3/remix\",\n headers={\n \"Api-Key\": \"<apiKey>\"\n },\n data={\n \"prompt\": \"A photo of a cat\",\n \"rendering_speed\": \"TURBO\"\n },\n files={\n \"image\": open(\"<file1>\", \"rb\"),\n }\n)\nprint(response.json())\nwith open('output.png', 'wb') as f:\n f.write(requests.get(response.json()['data'][0]['url']).content)\n" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Align fields in /v1/ideogram-v3/remix examples
The request example lists image_weight and aspect_ratio, but code samples omit them. Update the code snippets to include:
-F image_weight=50 \
-F aspect_ratio="1x2"🤖 Prompt for AI Agents (early access)
In src/libs/Ideogram/openapi.yaml around lines 774 to 794, the example request includes the fields image_weight and aspect_ratio, but these are missing in the curl and python code samples. Update both code samples to include the image_weight and aspect_ratio fields by adding -F image_weight=50 and -F aspect_ratio="1x2" to the curl command and adding corresponding entries in the data or files dictionary in the python example to match the request example.
Comment on lines
+654
to
+675
| x-fern-examples: | ||
| - request: | ||
| prompt: A photo of a cat sleeping on a couch. | ||
| rendering_speed: TURBO | ||
| aspect_ratio: 1x1 | ||
| response: | ||
| body: | ||
| created: '2000-01-23T04:56:07.0000000+00:00' | ||
| data: | ||
| - prompt: A photo of a cat sleeping on a couch. | ||
| resolution: 1024x1024 | ||
| is_image_safe: true | ||
| seed: 12345 | ||
| url: https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89 | ||
| style_type: GENERAL | ||
| code-samples: | ||
| - sdk: curl | ||
| code: "curl -X POST https://api.ideogram.ai/v1/ideogram-v3/generate \\\n -H \"Api-Key: <apiKey>\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F prompt=\"A photo of a cat sleeping on a couch.\" \\\n -F rendering_speed=\"TURBO\"\n" | ||
| - sdk: python | ||
| code: "import requests\n\n# Generate with Ideogram 3.0 (POST /v1/ideogram-v3/generate)\nresponse = requests.post(\n \"https://api.ideogram.ai/v1/ideogram-v3/generate\",\n headers={\n \"Api-Key\": \"<apiKey>\"\n },\n json={\n \"prompt\": \"A picture of a cat\",\n \"rendering_speed\": \"TURBO\"\n }\n)\nprint(response.json())\nwith open('output.png', 'wb') as f:\n f.write(requests.get(response.json()['data'][0]['url']).content)\n\n# Generate with style reference images\nresponse = requests.post(\n \"https://api.ideogram.ai/v1/ideogram-v3/generate\",\n headers={\n \"Api-Key\": \"<apiKey>\"\n },\n data={\n \"prompt\": \"A picture of a cat\",\n \"aspect_ratio\": \"3x1\"\n },\n files=[\n (\"style_reference_images\", open(\"style_reference_image_1.png\", \"rb\")),\n (\"style_reference_images\", open(\"style_reference_image_2.png\", \"rb\")),\n ]\n)\nprint(response.json())\nwith open('output.png', 'wb') as f:\n f.write(requests.get(response.json()['data'][0]['url']).content)\n" | ||
| - sdk: typescript | ||
| code: "const formData = new FormData();\nformData.append('prompt', 'A photo of a cat');\nformData.append('rendering_speed', 'TURBO');\n// To add style reference images, uncomment the following lines\n// formData.append('style_reference_images', '<style_reference_image_1>');\n// formData.append('style_reference_images', '<style_reference_image_2>');\nconst response = await fetch('https://api.ideogram.ai/v1/ideogram-v3/generate', {\n method: 'POST',\n headers: { 'Api-Key': '<apiKey>' },\n body: formData\n});\nconst data = await response.json();\nconsole.log(data);\n" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Sync fields between request example and code samples for /v1/ideogram-v3/generate
The example request includes aspect_ratio, but code samples omit it and mix in different prompt text. Align these:
- Ensure the curl snippet includes
-F aspect_ratio="1x1". - Match the JSON payload in SDK examples to the documented fields and values.
🤖 Prompt for AI Agents (early access)
In src/libs/Ideogram/openapi.yaml around lines 654 to 675, the request example for the /v1/ideogram-v3/generate endpoint includes the field aspect_ratio with value "1x1", but the code samples omit this field and use different prompt text. To fix this, update the curl snippet to include -F aspect_ratio="1x1" and modify the JSON payloads in the Python and TypeScript SDK examples to match the documented request fields exactly, using prompt "A photo of a cat sleeping on a couch." and rendering_speed "TURBO" along with aspect_ratio "1x1" where applicable.
Comment on lines
+836
to
+857
| x-fern-examples: | ||
| - request: | ||
| prompt: Add a forest in the background | ||
| magic_prompt: ON | ||
| rendering_speed: QUALITY | ||
| response: | ||
| body: | ||
| created: '2000-01-23T04:56:07.0000000+00:00' | ||
| data: | ||
| - prompt: Add a forest in the background | ||
| resolution: 1280x800 | ||
| is_image_safe: true | ||
| seed: 12345 | ||
| url: https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89 | ||
| style_type: GENERAL | ||
| code-samples: | ||
| - sdk: curl | ||
| code: "curl -X POST https://api.ideogram.ai/v1/ideogram-v3/replace-background \\\n -H \"Api-Key: <apiKey>\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F image=@<file1> \\\n -F prompt=\"Add a forest in the background\"\n" | ||
| - sdk: python | ||
| code: "import requests\n\nresponse = requests.post(\n \"https://api.ideogram.ai/v1/ideogram-v3/replace-background\",\n headers={\n \"Api-Key\": \"<apiKey>\" \n },\n data={\n \"prompt\": \"Add a forest in the background\",\n \"magic_prompt\": \"ON\"\n },\n files={\n \"image\": open(\"<file1>\", \"rb\"),\n }\n)\nprint(response.json())\nwith open('output.png', 'wb') as f:\n f.write(requests.get(response.json()['data'][0]['url']).content)\n" | ||
| - sdk: typescript | ||
| code: "const formData = new FormData();\nformData.append('prompt', 'Add a forest in the background');\nformData.append('image', '<file1>');\nconst response = await fetch('https://api.ideogram.ai/v1/ideogram-v3/replace-background', {\n method: 'POST',\n headers: { 'Api-Key': '<apiKey>' },\n body: formData\n});\nconst data = await response.json();\nconsole.log(data);\n" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Correct /v1/ideogram-v3/replace-background examples
The request example shows magic_prompt and rendering_speed, but code samples only include prompt (and miss attaching image). Align all examples and SDK snippets to:
- Attach the binary
imagefield. - Include both
magic_promptandrendering_speedas shown in the spec.
🤖 Prompt for AI Agents (early access)
In src/libs/Ideogram/openapi.yaml around lines 836 to 857, the example requests and SDK code samples for the /v1/ideogram-v3/replace-background endpoint are inconsistent. The request example includes magic_prompt and rendering_speed fields and attaches an image, but the code samples omit rendering_speed and do not properly attach the binary image file. Update all SDK code samples to include the magic_prompt and rendering_speed fields in the request body and ensure the image file is correctly attached as a binary file in the multipart/form-data payload, matching the request example.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
Documentation
New Features
Bug Fixes
Refactor