Ideogram Account API

openapi: 3.2.0
info:
  title: Ideogram API v2 Account API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: Account
paths:
  /v2/account/api-keys:
    get:
      operationId: account_get_account_api_keys
      summary: List API keys
      description: 'Lists the API keys in your organization. Key material is redacted —

        the full key is only shown once, when it is created. Disabled and

        archived keys are included (see each key''s `status`) so historical

        usage can always be matched to the key that generated it.


        Requires an API key whose owner is an organization admin. Keys owned

        by other members receive a 404.'
      tags:
      - Account
      responses:
        '200':
          description: The organization's API keys, redacted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAccountApiKeysResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: No organization with billing access was found for this credential.
          content:
            application/json:
              schema:
                description: Any type
      security:
      - ApiKeyAuth: []
  /v2/account/invoices:
    get:
      operationId: account_get_account_invoices
      summary: List invoices
      description: 'Returns your organization''s invoices with their line items — the

        billing record your usage reports reconcile against. Amounts are

        decimal strings in the invoice''s currency.


        Requires an API key whose owner is an organization admin. Keys owned

        by other members receive a 404.'
      tags:
      - Account
      responses:
        '200':
          description: The organization's invoices. Empty when no billing history exists yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAccountInvoicesResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: No organization with billing access was found for this credential.
          content:
            application/json:
              schema:
                description: Any type
      security:
      - ApiKeyAuth: []
  /v2/account/usage:
    get:
      operationId: account_get_account_usage
      summary: Get usage and spend
      description: 'Returns your organization''s billed API usage as dense time buckets of

        line items. Every line item carries the billed dollar amount; products

        billed per item also carry `billed_units` (unit, quantity, and unit

        price, where `quantity × unit_price = cost_total`). Usage-priced

        products (billed by metered provider usage) report `cost_total` only.


        Buckets cover the requested range completely — a bucket with no line

        items means no billed usage in that window. Line items are unique per

        bucket on (`product`, `dimensions`, `api_key.id`, unit price). Usage

        billed without an API key (requests authenticated as a user session)

        is included with `api_key` absent, so totals always reconcile with

        your invoices.

        `product` and `endpoint` are stable identifiers safe to aggregate on;

        `description` is display text and may be reworded at any time.


        Usage data may lag live traffic by a few minutes, and responses may be

        cached briefly, so this endpoint is for reporting rather than

        real-time monitoring.


        Requires an API key whose owner is an organization admin. Keys owned

        by other members receive a 404.'
      tags:
      - Account
      parameters:
      - name: start_time
        in: query
        description: Start of the reporting range (RFC 3339). Snapped down to the containing bucket boundary (UTC).
        required: true
        schema:
          type: string
          format: date-time
      - name: end_time
        in: query
        description: End of the reporting range (RFC 3339), exclusive. Snapped up to the next bucket boundary (UTC). Defaults to now.
        required: false
        schema:
          type: string
          format: date-time
      - name: bucket_width
        in: query
        description: Bucket granularity. `1d` allows ranges up to 92 days per request; `1h` allows up to 168 hours. Page through longer histories by moving `start_time` back across successive requests.
        required: false
        schema:
          $ref: '#/components/schemas/V2AccountUsageGetParametersBucketWidth'
          default: 1d
      - name: sources
        in: query
        description: Which billing sources to include. `api` is usage from API requests; `app` is web-app usage, attributed to the member who generated it. Defaults to both, so report totals reconcile with invoices.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/V2AccountUsageGetParametersSourcesSchemaItems'
          default:
          - api
          - app
      responses:
        '200':
          description: Bucketed usage for the requested range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountUsageResponse'
        '400':
          description: Invalid time range, bucket width, or filters.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: No organization with billing access was found for this credential.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                description: Any type
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ListAccountInvoicesResponse:
      type: object
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/AccountInvoice'
          description: The organization's invoices.
      required:
      - invoices
      title: ListAccountInvoicesResponse
    AccountApiKeyStatus:
      type: string
      enum:
      - active
      - disabled
      - archived
      title: AccountApiKeyStatus
    GetAccountUsageResponse:
      type: object
      properties:
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/AccountUsageBucket'
          description: Dense, chronological buckets covering the requested range.
      required:
      - buckets
      title: GetAccountUsageResponse
    AccountInvoice:
      type: object
      properties:
        start_time:
          type: string
          format: date-time
          description: Start of the invoice period.
        end_time:
          type: string
          format: date-time
          description: End of the invoice period.
        issued_time:
          type:
          - string
          - 'null'
          format: date-time
          description: When the invoice was issued, when it has been.
        paid_time:
          type:
          - string
          - 'null'
          format: date-time
          description: When the invoice was paid, when it has been.
        status:
          $ref: '#/components/schemas/AccountInvoiceStatus'
        total:
          type: string
          description: Invoice total in `currency_code`, as a decimal string.
        currency_code:
          type: string
          description: ISO 4217 currency code of the amounts on this invoice.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/AccountInvoiceLineItem'
          description: The invoice's charges.
      required:
      - start_time
      - end_time
      - status
      - total
      - currency_code
      - line_items
      title: AccountInvoice
    AccountUsageBucket:
      type: object
      properties:
        start_time:
          type: string
          format: date-time
          description: Start of the bucket window (inclusive, UTC).
        end_time:
          type: string
          format: date-time
          description: End of the bucket window (exclusive, UTC).
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/AccountUsageLineItem'
          description: Usage billed in this window. Empty when nothing was billed.
      required:
      - start_time
      - end_time
      - line_items
      title: AccountUsageBucket
    AccountUsageLineItemSource:
      type: string
      enum:
      - api
      - app
      description: Which billing surface the usage came through. `api` usage is attributed to an API key when one was used; `app` usage is attributed to the member who generated it.
      title: AccountUsageLineItemSource
    ListAccountApiKeysResponse:
      type: object
      properties:
        api_keys:
          type: array
          items:
            $ref: '#/components/schemas/AccountApiKey'
          description: All API keys in the organization, newest first.
      required:
      - api_keys
      title: ListAccountApiKeysResponse
    AccountInvoiceStatus:
      type: string
      enum:
      - draft
      - pending_payment
      - paid
      - voided
      description: Status of the invoice
      title: AccountInvoiceStatus
    AccountInvoiceLineItem:
      type: object
      properties:
        description:
          type: string
          description: Display name of the charged product. Not an identifier.
        quantity:
          type: string
          description: Number of billed units, as a decimal string.
        unit_price:
          type: string
          description: Price per unit in `currency_code`, as a decimal string.
        cost_total:
          type: string
          description: Total charged amount in `currency_code`, as a decimal string.
        currency_code:
          type: string
          description: ISO 4217 currency code of the amounts on this line item.
        api_key:
          $ref: '#/components/schemas/AccountUsageApiKey'
      required:
      - description
      - quantity
      - unit_price
      - cost_total
      - currency_code
      description: One charged product on an invoice.
      title: AccountInvoiceLineItem
    AccountUsageApiKey:
      type: object
      properties:
        id:
          type: string
          description: The API key's id, as listed by `GET /v2/account/api-keys`.
        redacted_key:
          type:
          - string
          - 'null'
          description: The first characters of the key followed by bullets.
        label:
          type:
          - string
          - 'null'
          description: The key's user-supplied label, when one is set.
      required:
      - id
      description: The API key the usage was billed to, in redacted form.
      title: AccountUsageApiKey
    V2AccountUsageGetParametersBucketWidth:
      type: string
      enum:
      - 1d
      - 1h
      default: 1d
      title: V2AccountUsageGetParametersBucketWidth
    AccountUsageBilledUnits:
      type: object
      properties:
        unit:
          type: string
          description: What one billed unit is (for example `image`).
        quantity:
          type: string
          description: Number of units billed, as a decimal string.
        unit_price:
          type: string
          description: Price per unit in `currency_code`, as a decimal string.
      required:
      - unit
      - quantity
      - unit_price
      description: Per-unit detail for products billed per item. `quantity × unit_price` always equals the line item's `cost_total`.
      title: AccountUsageBilledUnits
    AccountUsageLineItem:
      type: object
      properties:
        product:
          type: string
          description: Stable identifier of the public pricing catalog entry this charge was billed under, at the granularity the pricing page prices it (for example one entry per quality and resolution). `unknown` when a historical charge can no longer be attributed; its cost is still included.
        endpoint:
          type: string
          description: The API endpoint path this product belongs to.
        description:
          type: string
          description: Name of the public pricing catalog entry, as shown on the pricing page. Not an identifier.
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: Pricing dimensions this line item was billed under, for products priced per dimension (for example rendering speed).
        cost_total:
          type: string
          description: Total billed amount in `currency_code`, as a decimal string.
        currency_code:
          type: string
          description: ISO 4217 currency code of the amounts on this line item.
        source:
          $ref: '#/components/schemas/AccountUsageLineItemSource'
          description: Which billing surface the usage came through. `api` usage is attributed to an API key when one was used; `app` usage is attributed to the member who generated it.
        api_key:
          $ref: '#/components/schemas/AccountUsageApiKey'
        user_email:
          type:
          - string
          - 'null'
          description: Email address of the member who generated the usage. Only present on `app` usage.
        billed_units:
          $ref: '#/components/schemas/AccountUsageBilledUnits'
      required:
      - product
      - endpoint
      - description
      - cost_total
      - currency_code
      - source
      description: One billed rate for one billing actor within one time bucket.
      title: AccountUsageLineItem
    AccountApiKey:
      type: object
      properties:
        api_key_id:
          type: string
          description: Base64 encoded API key ID
        redacted_api_key:
          type: string
          description: A redacted text snippet of the API key. Contains the first 4 characters of the API key
        creation_time:
          type: string
          format: date-time
          description: The date at which the API key was created
        status:
          $ref: '#/components/schemas/AccountApiKeyStatus'
        label:
          type:
          - string
          - 'null'
          description: An optional user-supplied label for managing the API key
        creator_display_label:
          type:
          - string
          - 'null'
          description: Name of the member who created the key, falling back to their display handle when no name is set. Null on keys created before creators were recorded, and on workspace types whose keys are shared rather than owned by one member.
      required:
      - api_key_id
      - redacted_api_key
      - creation_time
      - status
      title: AccountApiKey
    V2AccountUsageGetParametersSourcesSchemaItems:
      type: string
      enum:
      - api
      - app
      title: V2AccountUsageGetParametersSourcesSchemaItems
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"