feat:OpenAPI: mgmt credits/spend endpoints, results endpoint, auth changes #107
Conversation
WalkthroughThe OpenAPI spec at src/libs/Ideogram/openapi.yaml adds two management GET endpoints for credits and spend commits, replaces the internal batch status path with a results-based endpoint, introduces several new response schemas, updates SamplingRequestParams.aspect_ratio, expands MagicPromptVersionEnum, and refines the ApiKeyAuth security scheme. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant C as Client
participant API as Ideogram API
participant Auth as BearerAuth
rect rgba(230,245,255,0.5)
note over C,API: Retrieve user credit metrics
C->>API: GET /manage/api/credits
API->>Auth: Validate token
Auth-->>API: OK
API-->>C: 200 GetUserCreditsResponse
end
rect rgba(230,245,255,0.5)
note over C,API: Retrieve spend-commit info
C->>API: GET /manage/api/spend_commit
API->>Auth: Validate token
Auth-->>API: OK
API-->>C: 200 SpendCommitInfoResponse (commits[])
end
sequenceDiagram
autonumber
participant Client
participant API as Ideogram API
participant Batch as Batch Service
rect rgba(240,255,240,0.6)
note over Client,API: Fetch batch results (replaces status/tfrecord)
Client->>API: GET /internal/batch/get-maybe-batch-results/{job_id}
API->>Batch: Query job status/results
alt Job finished
Batch-->>API: job_status=done, results[]
API-->>Client: 200 InternalBatchResultsResponse (results[])
else Job running
Batch-->>API: job_status=in_progress
API-->>Client: 200 InternalBatchResultsResponse (no/partial results)
end
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
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. Comment |
![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: 1
🧹 Nitpick comments (10)
src/libs/Ideogram/openapi.yaml (10)
183-183: Fix typos: “Evalution” → “Evaluation”.There are multiple user‑facing misspellings of “Evaluation” around the batch endpoints. Please correct across this path group to avoid leaking typos to SDKs/docs.
Apply where applicable:
- summary: Initiate Batch Magic Prompt Evalution + summary: Initiate Batch Magic Prompt EvaluationAnd similarly in descriptions/errors that still read “evalution”.
209-239: Endpoint naming and status semantics for results retrieval.“get-maybe-batch-results” is awkward and couples verb+condition into the path. Prefer a resource‑oriented path and 202 when pending.
Proposed shape:
- '/internal/batch/get-maybe-batch-results/{job_id}': + '/internal/batch/{job_id}/results': get: - summary: Get Batch Magic Prompt Job Results if available. + summary: Get batch job results - description: "Gets the results of a batch magic prompt job if available.\n" + description: "Gets results for a batch magic prompt job. Returns 202 if results are not ready." responses: - '200': - description: Batch magic prompt job results if available. + '200': + description: Results ready. content: application/json: schema: $ref: '#/components/schemas/InternalBatchResultsResponse' + '202': + description: Results not ready yet.If you keep the existing path, consider at least adding the 202 response.
219-224: Tighten parameter docs with examples and constraints.Add an example for job_id and optionally a format/pattern (e.g., UUID/Base64) to improve client generation and validation.
- name: job_id in: path - description: The ID of the batch job to check results for + description: The ID of the batch job to check results for. Expected to be a URL‑safe Base64 encoded UUID. required: true style: simple schema: - type: string + type: string + example: JRPVD7jWR1aTBYiJ0UFVOg==
371-410: Query param types for dates and examples.
- start_date/end_date are documented as “dates” but typed as date‑time. If you only need calendar days, use format: date; otherwise specify timezone expectations. Also add examples and clarify inclusivity.
- - name: start_date + - name: start_date in: query - description: Start date to look back for calculating average daily spend and other metrics + description: Start date (inclusive) used to compute spend metrics. If a time component is provided, it will be interpreted in UTC. required: true schema: - type: string - format: date-time + type: string + format: date-time + example: '2025-01-01T00:00:00Z' - name: end_date in: query - description: 'Inclusive end date to look back for calculating average daily spend and other metrics. If not provided, the current date will be used.' + description: 'Inclusive end timestamp used to compute spend metrics. Defaults to current time (UTC) if omitted.' schema: type: string format: date-time + example: '2025-09-19T23:59:59Z' + - name: organization_id + example: JRPVD7jWR1aTBYiJ0UFVOg==If day‑level granularity is sufficient, switch both to format: date.
1938-1954: Strengthen result schema: job_status enum, image URL format, and better examples.
- Make job_status an enum for predictable client code.
- Enforce image_url as uri and provide a realistic example.
properties: job_status: title: job_status - type: string - description: The status of the batch generation job. - example: COMPLETE + type: string + description: The status of the batch generation job. + enum: [PENDING, RUNNING, COMPLETE, FAILED] + example: COMPLETE results: title: results type: array items: $ref: '#/components/schemas/InternalBatchResultsResponse_results_inner' description: 'The batch generation results, with each entry containing a prompt and its corresponding image URL.' @@ example: job_status: COMPLETE results: - - image_url: image_url + - image_url: https://ideogram.ai/api/images/direct/abc123 prompt: a cat - - image_url: image_url + - image_url: https://ideogram.ai/api/images/direct/def456 prompt: a catAlso applies to: 1956-1961
2895-2912: Rename inner type and add URL format to improve SDK ergonomics.Generator‑style name “InternalBatchResultsResponse_results_inner” is noisy. Consider a reusable, clear name and enforce URI format.
- InternalBatchResultsResponse_results_inner: + BatchResultItem: title: InternalBatchResultsResponse_results_inner @@ image_url: title: image_url - type: string + type: string + format: uri description: The URL of the generated image. - example: - image_url: image_url + example: + image_url: https://ideogram.ai/api/images/direct/abc123 prompt: a catFollow up: update the array item $ref to point to BatchResultItem.
1882-1884: Outdated cross‑reference to deprecated status endpoint.Description still says “for /internal/batch/status GET request”. Update to reference the new results endpoint.
- description: A response for batch magic prompt evalution containing relavent information for /internal/batch/status GET request to find out if the batch generation has completed. + description: A response containing information necessary to query batch results via GET /internal/batch/{job_id}/results.
371-410: Security model consistency: internal vs manage./manage endpoints correctly require BearerAuth. The /internal/batch endpoints inherit global ApiKeyAuth only—verify this is intended for “internal” surfaces, or add explicit security (e.g., Bearer + feature flag).
If these must be shielded, add:
get: + security: + - BearerAuth: []Operationally, also gate on server‑side feature flags.
Also applies to: 434-469, 2925-2927
2317-2339: Consider requiring available_credits or documenting when it’s absent.available_credits is optional but will be consumed by clients. Either mark it required or document nullability/absence semantics.
- required: - - average_daily_spend - - total_spend + required: + - average_daily_spend + - total_spend + # consider: available_creditsIf it can be unavailable (e.g., metered‑only orgs), state that explicitly.
347-370: Path naming consistency: prefer hyphens or nouns over underscores.You use underscores in /manage/api/add_credits and /manage/api/spend_commit, while most other paths are hyphenated or noun‑based. Standardize for API polish.
Examples:
- /manage/api/add-credits
- /manage/api/spend-commit
Also applies to: 371-410, 434-469
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (21)
src/libs/Ideogram/Generated/Ideogram.BatchClient.GetMaybeBatchResults.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.BatchClient.PostBatch.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IBatchClient.GetMaybeBatchResults.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IBatchClient.PostBatch.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IManageClient.GetUserCredits.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.IManageClient.GetUserSpendCommitInfo.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.JsonSerializerContextTypes.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.ManageClient.GetUserCredits.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.ManageClient.GetUserSpendCommitInfo.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.GetUserCreditsResponse.Json.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.GetUserCreditsResponse.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.InternalBatchResultsResponse.Json.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.InternalBatchResultsResponse.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.InternalBatchResultsResponseResultsInner.Json.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.InternalBatchResultsResponseResultsInner.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.MagicPromptVersionEnum.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.SamplingRequestParams.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.SpendCommitInfo.Json.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.SpendCommitInfo.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.SpendCommitInfoResponse.Json.g.csis excluded by!**/generated/**src/libs/Ideogram/Generated/Ideogram.Models.SpendCommitInfoResponse.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Ideogram/openapi.yaml(12 hunks)
🔇 Additional comments (2)
src/libs/Ideogram/openapi.yaml (2)
1890-1894: Aspect ratio wrapper looks good; examples aligned to V3 values.No issues; the allOf wrapper plus example 1x1 matches AspectRatioV3.
Please confirm downstream generators (e.g., fern/openapi‑typescript) still render a single union type for aspect_ratio with this wrapper.
Also applies to: 1926-1936
2915-2919: Auth scheme doc improvement looks good.Explicit header name and info func are helpful; examples elsewhere already use Api-Key. No action needed.
| get: | ||
| tags: | ||
| - manage | ||
| summary: Retrieve user spend commit information | ||
| operationId: get_user_spend_commit_info | ||
| parameters: | ||
| - name: organization_id | ||
| in: query | ||
| description: Base64 encoded organization ID to filter spend commit information for a specific organization | ||
| required: true | ||
| schema: | ||
| type: string | ||
| responses: | ||
| '200': | ||
| description: User spend commit information retrieved successfully | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/SpendCommitInfoResponse' | ||
| example: | ||
| commits: | ||
| - commit_spend_balance: | ||
| currency_code: USD | ||
| amount: 7500 | ||
| commit_amount: | ||
| currency_code: USD | ||
| amount: 10000 | ||
| commit_start_date: '2025-01-01' | ||
| commit_end_date: '2025-12-31T23:59:59.0000000+00:00' | ||
| '401': | ||
| description: Not authorized | ||
| '403': | ||
| description: Not authorized | ||
| security: | ||
| - BearerAuth: [ ] | ||
| x-openapi-router-controller: external_api.generated.openapi.controllers.manage_controller |
There was a problem hiding this comment.
Spend commit example uses inconsistent date formats.
commit_start_date is schema format: date-time but example is date‑only. Align to date‑time.
- commit_start_date: '2025-01-01'
+ commit_start_date: '2025-01-01T00:00:00Z'Also consider adding timezone note in the endpoint description.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| get: | |
| tags: | |
| - manage | |
| summary: Retrieve user spend commit information | |
| operationId: get_user_spend_commit_info | |
| parameters: | |
| - name: organization_id | |
| in: query | |
| description: Base64 encoded organization ID to filter spend commit information for a specific organization | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| description: User spend commit information retrieved successfully | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/SpendCommitInfoResponse' | |
| example: | |
| commits: | |
| - commit_spend_balance: | |
| currency_code: USD | |
| amount: 7500 | |
| commit_amount: | |
| currency_code: USD | |
| amount: 10000 | |
| commit_start_date: '2025-01-01' | |
| commit_end_date: '2025-12-31T23:59:59.0000000+00:00' | |
| '401': | |
| description: Not authorized | |
| '403': | |
| description: Not authorized | |
| security: | |
| - BearerAuth: [ ] | |
| x-openapi-router-controller: external_api.generated.openapi.controllers.manage_controller | |
| get: | |
| tags: | |
| - manage | |
| summary: Retrieve user spend commit information | |
| operationId: get_user_spend_commit_info | |
| parameters: | |
| - name: organization_id | |
| in: query | |
| description: Base64 encoded organization ID to filter spend commit information for a specific organization | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| description: User spend commit information retrieved successfully | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/SpendCommitInfoResponse' | |
| example: | |
| commits: | |
| - commit_spend_balance: | |
| currency_code: USD | |
| amount: 7500 | |
| commit_amount: | |
| currency_code: USD | |
| amount: 10000 | |
| commit_start_date: '2025-01-01T00:00:00Z' | |
| commit_end_date: '2025-12-31T23:59:59.0000000+00:00' | |
| '401': | |
| description: Not authorized | |
| '403': | |
| description: Not authorized | |
| security: | |
| - BearerAuth: [ ] | |
| x-openapi-router-controller: external_api.generated.openapi.controllers.manage_controller |
🤖 Prompt for AI Agents
In src/libs/Ideogram/openapi.yaml around lines 434 to 469, the example for spend
commit uses inconsistent date formats (commit_start_date is date-only while the
schema expects date-time); update the example so commit_start_date is a full
date-time string with timezone (e.g. ISO 8601 with time and offset) to match the
schema, and add a short timezone note to the endpoint summary/description
indicating that all dates are ISO 8601 date-time strings with timezone (UTC or
offset) so consumers know the expected format.
Summary by CodeRabbit
New Features
Refactor
Documentation