Recipe API Image Generation API

openapi: 3.2.0
info:
  title: Recipe Image Generation API
  description: 'B2B Recipe API providing structured recipes with comprehensive nutrition data.


    **Quick Start** - Try it now (no API key needed):

    ```

    curl https://recipe-api.com/api/v1/dinner

    ```


    **Sample Responses** - All endpoints below show example responses so you can evaluate the data structure before signing up. Expand any endpoint to see what you''ll receive.


    **Authentication** - Protected endpoints require an `X-API-Key` header. Get your key at [recipe-api.com](https://recipe-api.com/signup).'
  version: 1.0.0
  contact:
    email: paul@recipe-api.com
servers:
- url: https://recipe-api.com
  description: Production
tags:
- name: Image Generation
paths:
  /api/v1/image-generate:
    post:
      tags:
      - Image Generation
      summary: Generate food photography from a recipe
      description: Generates a photorealistic AI food photograph for an existing recipe. Requires image credits purchased from the dashboard by paid plans. Requests count against your plan's shared per-minute rate limit.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerateRequest'
            example:
              recipe_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              aspect_ratio: '4:3'
      responses:
        '200':
          description: JPEG image bytes. Metadata in response headers (X-Credits-Remaining, X-Credits-Total, X-Recipe-Id, X-Aspect-Ratio, X-Model).
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
          headers:
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credits remaining after this request
            X-Credits-Total:
              schema:
                type: integer
              description: Total credits purchased
            X-Recipe-Id:
              schema:
                type: string
                format: uuid
              description: Recipe UUID
            X-Aspect-Ratio:
              schema:
                type: string
              description: Aspect ratio used
            X-Model:
              schema:
                type: string
              description: AI model used
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: No image credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NO_IMAGE_CREDITS
                  message: No image credits remaining. Purchase a credit pack from your dashboard at /keys.
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited. Returned when your plan's shared per-minute rate limit is exceeded (RATE_LIMITED) or the image generation limit is exceeded (IMAGE_GEN_LIMIT_EXCEEDED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  summary: Per-minute rate limit exceeded
                  value:
                    error:
                      code: RATE_LIMITED
                      message: Per-minute rate limit exceeded. Retry in a moment.
                image_gen_limit:
                  summary: Image generation limit exceeded
                  value:
                    error:
                      code: IMAGE_GEN_LIMIT_EXCEEDED
                      message: Monthly image generation limit reached (500). Credits reset at the start of your next billing period.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying (present when the per-minute rate limit triggered the 429)
        '500':
          description: Image processing error (credit refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: IMAGE_GENERATION_FAILED
                  message: Failed to process generated image. Please try again (credit refunded).
        '502':
          description: AI model error (credit refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: IMAGE_GENERATION_FAILED
                  message: Failed to generate image. Please try again (credit refunded).
        '504':
          description: AI model timeout (credit refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: IMAGE_GENERATION_TIMEOUT
                  message: Image generation timed out. Please try again (credit refunded).
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Missing X-API-Key header
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid recipe ID format. Use UUID.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Recipe not found
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    ImageGenerateRequest:
      type: object
      required:
      - recipe_id
      properties:
        recipe_id:
          type: string
          format: uuid
          description: UUID of a public recipe to generate an image for
        aspect_ratio:
          type: string
          enum:
          - '1:1'
          - '3:4'
          - '4:3'
          - '9:16'
          - '16:9'
          default: '4:3'
          description: Aspect ratio of the generated image
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key in format `rapi_<key>`