openapi: 3.0.0
info:
  title: Article Generator API
  description: >-
    Complete API collection for AI-powered article generation, rewriting, image generation, and article suggestions.


    ## Features

    - Generate high-quality, SEO-optimized articles

    - Rewrite existing articles from URLs

    - Generate featured images for articles using AI

    - Customizable writing style, tone, and content parameters

    - WordPress-ready HTML output

    - Optional FAQ section generation


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Base URL

    ```
    https://use.api.co.id/article-generator
    ```


    ## Pricing Modes

    ### Pay As You Go (PAYG)

    - **Article Generation**: 1300 points per article

    - **Article Rewrite**: 1300 points per rewrite

    - **Image Generation**: 300 points per image

    - Points are deducted after successful generation

    - Returns `402 Payment Required` if balance is insufficient


    ### Bring Your Own Key (BYOK)

    - **Requirements**: Active premium subscription + configured Gemini/ChatGPT API keys

    - **Article Generation**: FREE (uses your own API keys)

    - **Article Rewrite**: FREE (uses your own API keys)

    - **Image Generation**: FREE

    - Configure API keys in the dashboard settings

    - If premium expires or keys are removed, falls back to PAYG mode


    ## Response Headers

    - `x-article-mode`: Indicates the pricing mode used (`pay_as_you_go` or `bring_your_own_key`)

  version: 2.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Article Generation
    description: Generate SEO-optimized articles from title and keywords.
  - name: Article Rewriter
    description: Rewrite article content from a URL.
  - name: Image Generation
    description: Generate featured images for articles using AI.
paths:
  /article-generator/generate:
    post:
      tags:
        - Article Generation
      summary: Generate Article
      description: >-
        Generate a high-quality, SEO-optimized article based on your parameters.

        ### Pricing

        - **PAYG mode**: 1300 points per article

        - **BYOK mode**: FREE (premium users with configured API keys)

        ### Response Headers

        - `x-article-mode`: `pay_as_you_go` or `bring_your_own_key`

        ### Error Responses

        - `401`: User not authenticated

        - `402`: Insufficient points balance (PAYG mode, need 1300 points)

        - `400`: Invalid request body or generation failed
      parameters:
        - name: x-api-co-id
          in: header
          required: true
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - keywords
                - language
                - writing_style
                - tone
                - search_intent
                - point_of_view
                - creativity_level
                - audience
              properties:
                title:
                  type: string
                  description: Article title or topic
                  example: What is REST API
                keywords:
                  type: array
                  items:
                    type: string
                  description: Array of keywords to optimize for
                  example:
                    - REST API
                    - web development
                    - API design
                allow_related_keyword:
                  type: boolean
                  description: Include related keywords (default false)
                  default: false
                  example: true
                language:
                  type: string
                  description: Article language
                  example: Indonesia
                writing_style:
                  type: array
                  items:
                    type: string
                  description: Array of writing styles
                  example:
                    - blog-friendly
                    - informative
                tone:
                  type: array
                  items:
                    type: string
                  description: Array of tones
                  example:
                    - friendly
                    - casual
                search_intent:
                  type: array
                  items:
                    type: string
                  description: Array of search intents
                  example:
                    - informational
                point_of_view:
                  type: array
                  items:
                    type: string
                  description: Array of perspectives
                  example:
                    - neutral
                creativity_level:
                  type: array
                  items:
                    type: string
                  description: Array of creativity levels
                  example:
                    - balanced
                audience:
                  type: string
                  description: Target audience description
                  example: developers and beginners
                additional_prompt:
                  type: string
                  description: Additional instructions for article generation
                  example: ''
                faq:
                  type: boolean
                  description: Add FAQ section at the bottom of the article (default false)
                  default: false
                  example: false
            example:
              title: What is REST API
              keywords:
                - REST API
                - web development
                - API design
              allow_related_keyword: true
              language: Indonesia
              writing_style:
                - blog-friendly
                - informative
              tone:
                - friendly
                - casual
              search_intent:
                - informational
              point_of_view:
                - neutral
              creativity_level:
                - balanced
              audience: developers and beginners
              additional_prompt: ''
              faq: false
      responses:
        '200':
          description: Successful response - Article generated
          headers:
            x-article-mode:
              description: Pricing mode used (pay_as_you_go or bring_your_own_key)
              schema:
                type: string
                example: pay_as_you_go
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
              examples:
                success:
                  summary: Success Response
                  value:
                    data:
                      meta:
                        title: What is REST API
                        keywords:
                          - REST API
                          - web development
                        main_keyword: REST API
                        language: Indonesia
                        search_intent: informational
                        audience: developers
                        description: Pelajari apa itu REST API, arsitektur, dan cara kerjanya dalam pengembangan web modern.
                        word_count: 1200
                      title: What is REST API
                      article: '<h2>Pengenalan REST API</h2><p>REST API adalah...</p>'
                    errors: null
        '400':
          description: Bad Request - Invalid request or generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient points balance (PAYG mode, need 1300 points)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_balance:
                  summary: Insufficient Balance (402)
                  value:
                    data: null
                    errors: 'Insufficient points balance. Article generation costs 1300 points. Please top up to continue.'
  /article-generator/article-rewriter-by-url:
    post:
      tags:
        - Article Rewriter
      summary: Rewrite Article by URL
      description: >-
        Fetch, validate, and rewrite article content from a URL. Returns rewritten article in the same format as article generator.

        ### Pricing

        - **PAYG mode**: 1300 points per rewrite

        - **BYOK mode**: FREE (premium users with configured API keys)

        ### Response Headers

        - `x-article-mode`: `pay_as_you_go` or `bring_your_own_key`

        ### Error Responses

        - `401`: User not authenticated

        - `402`: Insufficient points balance (PAYG mode, need 1300 points)

        - `400`: Invalid request body or rewrite failed

        - `503`: Article rewriter service not available
      parameters:
        - name: x-api-co-id
          in: header
          required: true
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - language
                - writing_style
                - tone
                - search_intent
                - point_of_view
                - creativity_level
                - audience
              properties:
                url:
                  type: string
                  format: uri
                  description: URL of the article to rewrite
                  example: https://example.com/article-to-rewrite
                allow_related_keyword:
                  type: boolean
                  description: Include related keywords (default false)
                  default: false
                  example: true
                language:
                  type: string
                  description: Output article language
                  example: Indonesia
                writing_style:
                  type: array
                  items:
                    type: string
                  description: Array of writing styles
                  example:
                    - blog-friendly
                    - informative
                tone:
                  type: array
                  items:
                    type: string
                  description: Array of tones
                  example:
                    - friendly
                    - casual
                search_intent:
                  type: array
                  items:
                    type: string
                  description: Array of search intents
                  example:
                    - informational
                point_of_view:
                  type: array
                  items:
                    type: string
                  description: Array of perspectives
                  example:
                    - neutral
                creativity_level:
                  type: array
                  items:
                    type: string
                  description: Array of creativity levels
                  example:
                    - balanced
                audience:
                  type: string
                  description: Target audience description
                  example: developers and beginners
                additional_prompt:
                  type: string
                  description: Additional instructions for rewriting
                  example: ''
                faq:
                  type: boolean
                  description: Add FAQ section at the bottom of the article (default false)
                  default: false
                  example: false
            example:
              url: https://example.com/article-to-rewrite
              allow_related_keyword: true
              language: Indonesia
              writing_style:
                - blog-friendly
                - informative
              tone:
                - friendly
                - casual
              search_intent:
                - informational
              point_of_view:
                - neutral
              creativity_level:
                - balanced
              audience: developers and beginners
              additional_prompt: ''
              faq: false
      responses:
        '200':
          description: Successful response - Article rewritten
          headers:
            x-article-mode:
              description: Pricing mode used (pay_as_you_go or bring_your_own_key)
              schema:
                type: string
                example: pay_as_you_go
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
              examples:
                success:
                  summary: Success Response
                  value:
                    data:
                      meta:
                        title: Panduan Lengkap REST API
                        keywords:
                          - REST API
                          - web development
                        main_keyword: REST API
                        language: Indonesia
                        search_intent: informational
                        audience: developers
                        description: Panduan lengkap memahami REST API dan implementasinya dalam pengembangan web modern.
                        word_count: 1500
                      title: Panduan Lengkap REST API
                      article: '<h2>Apa Itu REST API?</h2><p>REST API adalah...</p>'
                    errors: null
        '400':
          description: Bad Request - Invalid request or rewrite failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient points balance (PAYG mode, need 1300 points)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_balance:
                  summary: Insufficient Balance (402)
                  value:
                    data: null
                    errors: 'Insufficient points balance. Article rewrite costs 1300 points. Please top up to continue.'
        '503':
          description: Service Unavailable - Article rewriter service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /article-generator/image-generator:
    post:
      tags:
        - Image Generation
      summary: Generate Featured Image
      description: >-
        Generate a featured image for an article title using AI.

        ### Pricing

        - **PAYG mode**: 300 points per image

        - **BYOK mode**: FREE (premium users with configured API keys)

        ### Response Headers

        - `x-article-mode`: `pay_as_you_go` or `bring_your_own_key`

        ### Error Responses

        - `401`: User not authenticated

        - `402`: Insufficient points balance (PAYG mode, need 300 points)

        - `400`: Invalid request body or generation failed

        - `503`: Image generator service not available
      parameters:
        - name: x-api-co-id
          in: header
          required: true
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - article_title
              properties:
                article_title:
                  type: string
                  description: Title of the article to generate a featured image for
                  example: What is REST API
                return_webp:
                  type: boolean
                  description: If true, return base64-encoded WebP image instead of URL (default false)
                  default: false
                  example: false
            example:
              article_title: What is REST API
              return_webp: false
      responses:
        '200':
          description: Successful response - Image generated
          headers:
            x-article-mode:
              description: Pricing mode used (pay_as_you_go or bring_your_own_key)
              schema:
                type: string
                example: pay_as_you_go
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ImageUrlResponse'
                  - $ref: '#/components/schemas/ImageBase64Response'
              examples:
                url:
                  summary: Success Response (URL)
                  value:
                    data:
                      image_url: https://example.com/generated-image.png
                    errors: null
                webp:
                  summary: Success Response (WebP Base64)
                  value:
                    data:
                      image_base64: UklGRi4AAABXRUJQVlA4IC...
                      format: webp
                      size_bytes: 45230
                    errors: null
        '400':
          description: Bad Request - Invalid request or generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient points balance (PAYG mode, need 300 points)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_balance:
                  summary: Insufficient Balance (402)
                  value:
                    data: null
                    errors: 'Insufficient points balance. Image generation costs 300 points. Please top up to continue.'
        '503':
          description: Service Unavailable - Image generator service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ArticleResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          properties:
            meta:
              type: object
              properties:
                title:
                  type: string
                keywords:
                  type: array
                  items:
                    type: string
                main_keyword:
                  type: string
                language:
                  type: string
                search_intent:
                  type: string
                audience:
                  type: string
                description:
                  type: string
                word_count:
                  type: integer
            title:
              type: string
            article:
              type: string
              description: Complete article content in HTML format (WordPress-ready)
        errors:
          type: string
          nullable: true
    ImageUrlResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            image_url:
              type: string
              format: uri
              description: URL of the generated featured image (when return_webp=false)
        errors:
          type: string
          nullable: true
    ImageBase64Response:
      type: object
      properties:
        data:
          type: object
          properties:
            image_base64:
              type: string
              description: Base64-encoded WebP image (when return_webp=true)
            format:
              type: string
              example: webp
            size_bytes:
              type: integer
              description: Compressed image size in bytes
        errors:
          type: string
          nullable: true
    ErrorResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
        errors:
          type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-co-id
      description: Your API key for authentication
security:
  - ApiKeyAuth: []
