AI Content Drop Models API

openapi: 3.2.0
info:
  title: AI Content Drop Models API
  version: 2.7.0
  summary: Generate AI video and images programmatically, and read AI Content Drop's public content as plain text, markdown, or XML.
  description: 'The public REST API of https://aicontentdrop.com — generate AI video and images programmatically on your own account.


    **Authentication**: an API key created in your dashboard (Settings → Integrations). Keys look like `acd_live_…` and are sent as `Authorization: Bearer`. The index and the model catalogue need no key at all; everything that touches an account or spends credits does.


    **Generation is submit-and-poll**: POST returns a record immediately with status `generating`, then GET /v1/videos/{id} until `completed`. Credits are flat per model and are only charged on success — safety blocks, provider failures, and timeouts cost nothing.


    **Rate limits**: 120 requests/minute. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`; a 429 additionally sends `Retry-After` (seconds).


    **Errors** are always structured JSON, never HTML. /v1 read endpoints return `{"error": {"code", "message"}}`; the generation endpoints (shared with the website) return `{"error": "", "code"?: ""}`.


    **Versioning**: the version is in the URL path (`/v1`). A breaking change ships as a new path segment; the previous version keeps working for at least 180 days and is announced with `Deprecation` and `Sunset` response headers (RFC 9745 / RFC 8594) before it is removed. Policy: https://aicontentdrop.com/developers#versioning


    **Other protocols over the same capabilities**: MCP (Streamable HTTP) at POST /mcp, manifest at /.well-known/mcp.json; A2A (JSON-RPC 2.0) at POST /a2a; NLWeb at POST /ask. The read-only text/markdown content surface is documented separately at https://aicontentdrop.com/openapi-content.json.


    **Batch**: `POST /v1/batch` runs up to 20 read operations in one request; `POST /v1/models/cost` quotes up to 50 model/quantity pairs. Generation is never batched — see the endpoint description for why.


    **Sandbox**: send `X-Sandbox: true` on either generation endpoint, with or without a key, to rehearse the call for free.


    **GraphQL**: the same data is served at `POST https://aicontentdrop.com/graphql` with open introspection, Relay connections, and typed errors. SDL at https://aicontentdrop.com/graphql/schema.graphql, documentation at https://aicontentdrop.com/docs/graphql.'
  contact:
    name: AI Content Drop support
    email: support@aicontentdrop.com
    url: https://aicontentdrop.com/contact
  license:
    name: Content usage terms
    url: https://aicontentdrop.com/terms-of-use
servers:
- url: https://aicontentdrop.com
  description: Production
tags:
- name: Models
  description: Model catalogue and credit-cost estimates
paths:
  /v1/models:
    get:
      tags:
      - Models
      operationId: listModels
      summary: Model catalogue with credit costs
      description: Every generation model available on the platform with its flat per-generation credit cost. Model IDs use underscores (e.g. `kling_3_0`, `veo_3_fast`); dashed forms are accepted everywhere and normalized. No API key required; sending one is accepted and simply identifies the caller.
      x-openai-isConsequential: false
      security:
      - {}
      - ApiKeyAuth: []
      parameters:
      - name: type
        in: query
        description: Catalogue to list
        schema:
          type: string
          enum:
          - video
          - image
          default: video
      - name: max_credits
        in: query
        description: Only models costing at most this many credits per generation
        schema:
          type: number
      responses:
        '200':
          description: Model catalogue
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - type
                - count
                - models
                properties:
                  type:
                    type: string
                    enum:
                    - video
                    - image
                  count:
                    type: integer
                  note:
                    type: string
                  models:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - credits
                      properties:
                        id:
                          type: string
                          description: Model ID to pass to the generation endpoints
                        name:
                          type: string
                        credits:
                          type: number
                          description: Flat credit cost per generation
                      additionalProperties: true
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/plans:
    get:
      tags:
      - Models
      operationId: listPlans
      summary: Plans, prices, credit packs, and the free tier
      description: Subscription plans with their monthly price and credit allocation, the one-time top-up packs, and the free tier, derived from the same constants checkout bills against. No API key required. Use this instead of scraping the pricing page, and /v1/models for what a credit buys on each model.
      x-openai-isConsequential: false
      security:
      - {}
      - ApiKeyAuth: []
      responses:
        '200':
          description: Plans and prices
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plans'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/models/{id}/cost:
    get:
      tags:
      - Models
      operationId: estimateModelCost
      summary: Credit cost estimate for a model
      description: Quote the credit cost of one or more generations with a model before committing. Dashed IDs are normalized to underscores. No API key required; sending one is accepted and simply identifies the caller.
      x-openai-isConsequential: false
      security:
      - {}
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Model ID, e.g. kling_3_0
        schema:
          type: string
        example: kling_3_0
      - name: quantity
        in: query
        description: Number of generations to quote
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: Cost estimate
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - model_id
                - credits_each
                - credits_total
                properties:
                  model_id:
                    type: string
                  name:
                    type: string
                  credits_each:
                    type: number
                  quantity:
                    type: integer
                  credits_total:
                    type: number
                  type:
                    type: string
                    enum:
                    - video
                    - image
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/models/cost:
    post:
      tags:
      - Models
      operationId: estimateCostBatch
      summary: Cost estimate for many models at once
      description: Quote up to 50 model/quantity pairs in one request. Read-only — it never starts a generation. An agent planning a batch would otherwise loop the single-model endpoint and spend its rate-limit budget on arithmetic. A bad line returns a per-item error instead of failing the whole batch.
      x-openai-isConsequential: false
      security:
      - {}
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                    - model_id
                    properties:
                      model_id:
                        type: string
                        example: kling_3_0
                      quantity:
                        type: integer
                        minimum: 1
                        default: 1
      responses:
        '200':
          description: Per-item quotes plus the batch total
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - credits_total
                - items
                properties:
                  count:
                    type: integer
                  credits_total:
                    type: number
                    description: Sum across every item that resolved
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        model_id:
                          type: string
                        name:
                          type: string
                        credits_each:
                          type: number
                        quantity:
                          type: integer
                        credits_total:
                          type:
                          - number
                          - 'null'
                        type:
                          type: string
                        error:
                          type:
                          - object
                          - 'null'
                          properties:
                            code:
                              type: string
                            message:
                              type: string
        '400':
          description: Missing or oversized items array
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RateLimitReset:
      description: Seconds until the current window resets
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed in the current window (120/minute on /v1)
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
  schemas:
    RateLimitError:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: 429. Read Retry-After (header) or error.retry_after_seconds (body) and back off; they carry the same number.
    Error:
      type: object
      required:
      - error
      description: Every failure on the agent-facing surfaces (/v1, /graphql, /ask, /agent, /mcp) uses this envelope, on every status code. An HTML error page from these paths is a bug.
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this, never on the message text.
              enum:
              - invalid_request
              - invalid_json
              - payload_too_large
              - unauthorized
              - unauthenticated
              - invalid_client
              - forbidden
              - not_found
              - unknown_endpoint
              - unknown_model
              - method_not_allowed
              - unsupported_operation
              - unsupported_identity_type
              - missing_query
              - idempotency_conflict
              - insufficient_credits
              - safety_rejected
              - rate_limited
              - query_too_large
              - operation_failed
              - provider_error
              - internal_error
            message:
              type: string
              description: Human-readable explanation that names the failing field or resource, and what to do next.
            retry_after_seconds:
              type: integer
              minimum: 1
              description: Present on 429. Mirrors the Retry-After header. Wait this long before retrying; retrying sooner extends the window.
            documentation:
              type: string
              format: uri
              description: URL explaining this class of error.
            field:
              type: string
              description: 'Present on validation failures: the request field at fault.'
          additionalProperties: true
      examples:
      - error:
          code: rate_limited
          message: Rate limit exceeded. Wait 34 seconds and retry.
          retry_after_seconds: 34
          documentation: https://aicontentdrop.com/docs/rate-limits
    Plans:
      type: object
      required:
      - object
      - currency
      - free_tier
      - plans
      - credit_packs
      properties:
        object:
          type: string
          enum:
          - list
        currency:
          type: string
          enum:
          - usd
        billing_model:
          type: string
          description: 'Post-deduct: credits are charged only when a generation succeeds, so there is no refund path.'
        free_tier:
          type: object
          required:
          - available
          - credits
          - allocation
          properties:
            available:
              type: boolean
            credits:
              type: integer
              example: 10
            price_usd:
              type: number
              example: 0
            card_required:
              type: boolean
            allocation:
              type: string
              enum:
              - one_time
              description: Granted once, on email confirmation, and stamped so it cannot be replayed.
            renews:
              type: boolean
            email_confirmation_required:
              type: boolean
            signup_url:
              type: string
              format: uri
            agent_signup:
              type: string
              format: uri
              description: POST here with the human's address to have a magic link sent; an agent cannot complete signup alone.
        plans:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - price_usd_per_month
            - credits_per_month
            properties:
              id:
                type: string
                example: starter
              name:
                type: string
                example: Starter
              price_usd_per_month:
                type: number
                example: 19
              price_usd_per_month_billed_annually:
                type:
                - number
                - 'null'
                description: Monthly rate when billed annually, not a yearly total. Null when the plan has no annual option.
              credits_per_month:
                type: integer
                example: 150
              max_quality:
                type: string
                example: 720p
              popular:
                type: boolean
              features:
                type: array
                items:
                  type: string
              checkout_url:
                type: string
                format: uri
        credit_packs:
          type: array
          description: One-time top-ups. Credits from a pack do not expire with the billing period.
          items:
            type: object
            required:
            - id
            - credits
            - price_usd
            properties:
              id:
                type: string
                example: pack_150
              credits:
                type: integer
                example: 150
              price_usd:
                type: number
                example: 12
              usd_per_credit:
                type: number
                example: 0.08
              one_time:
                type: boolean
        per_model_costs:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
  responses:
    RateLimited:
      description: Rate limited. Read Retry-After (header) or error.retry_after_seconds (body) — they carry the same number — and wait that long. Retrying sooner extends the window rather than shortening it.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
    InternalError:
      description: Unexpected failure on our side. Retry once; nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource (or not owned by this account)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: acd_live_…
      description: 'API key created at https://aicontentdrop.com/settings/integrations (any account, free tier included). Sent as `Authorization: Bearer acd_live_…`. Keys are shown once at creation and may carry a daily credit ceiling.'
externalDocs:
  description: Developer documentation, versioning and deprecation policy
  url: https://aicontentdrop.com/docs/versioning
x-api-version: '2026-08-24'
x-versioning:
  strategy: url-path
  current: v1
  version_header: API-Version
  deprecation_policy: https://aicontentdrop.com/docs/versioning
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link; rel="deprecation"
  minimum_notice_days: 180
  breaking_changes: Ship at a new path (/v2). /v1 response shapes are additive only.