AI Content Drop Batch API

openapi: 3.2.0
info:
  title: AI Content Drop Batch 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: Batch
  description: Run many read operations in one request instead of looping.
paths:
  /v1/batch:
    post:
      tags:
      - Batch
      operationId: runBatch
      summary: Run several read operations in one request
      description: 'Dispatches up to 20 GET operations against the public read surface and returns their results in one envelope, so an agent acting on many items does not spend one request per item.


        **Reads only.** Generation is deliberately not batchable: a partial failure in a batch of money-spending calls leaves credits nobody can account for, so each generation keeps its own request and its own `Idempotency-Key`.


        **Per-item status.** An operation that fails carries its own `status` and `error`; the envelope is still 200. No API key is required for the paths it accepts.'
      x-openai-isConsequential: false
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - operations
              properties:
                operations:
                  type: array
                  minItems: 1
                  maxItems: 20
                  description: The operations to run, in order.
                  items:
                    type: object
                    required:
                    - method
                    - path
                    properties:
                      id:
                        type: string
                        description: Your label for this operation, echoed in the result. Defaults to the array index.
                      method:
                        type: string
                        enum:
                        - GET
                        description: Only GET is accepted.
                      path:
                        type: string
                        description: 'A read path: /v1/models or /v1/models/{id}/cost, with an optional query string.'
                        example: /v1/models/kling_3_0/cost?quantity=3
      responses:
        '200':
          description: Every operation was dispatched. Inspect each result for its own status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Operations received.
                  succeeded:
                    type: integer
                    description: Operations that returned 200.
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: integer
                          description: HTTP status this operation would have returned on its own.
                        body:
                          type: object
                          nullable: true
                          description: The operation result, or null when it failed.
                        error:
                          type: object
                          nullable: true
                          properties:
                            code:
                              type: string
                            message:
                              type: string
        '400':
          description: No operations, more than 20, or a malformed envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. Read Retry-After (header) or error.retry_after_seconds (body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  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
  responses:
    InternalError:
      description: Unexpected failure on our side. Retry once; nothing was charged.
      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.