AI Content Drop Authentication API

openapi: 3.2.0
info:
  title: AI Content Drop Authentication 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: Authentication
paths:
  /v1/auth/register:
    post:
      operationId: initiateSignup
      summary: Start account creation for a human
      description: 'Sends the given address a sign-in link and returns 202. The account is not usable until the human clicks it — that click is what confirms the mailbox and releases the 10 free credits, and it is the one step an agent cannot perform. There is deliberately NO password parameter: an agent should never hold a user''s password. An address that already has an account gets the same response, so this cannot be used to test who is registered. Rate limited to 5 per hour per IP.'
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: The HUMAN's email address. They must be able to open it.
            examples:
              default:
                value:
                  email: person@example.com
      responses:
        '202':
          description: Sign-in link sent. Tell the human to click it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupInitiated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          description: The sign-in email could not be sent. The human can sign up at /register.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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
  responses:
    BadRequest:
      description: The request was malformed. `error.code` names the class of problem and `error.message` names the field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  schemas:
    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
    SignupInitiated:
      type: object
      required:
      - status
      - email
      - message_for_human
      - next_step
      - free_credits
      description: 202 from POST /v1/auth/register. The account is NOT usable yet — a human must click the emailed link. Relay `message_for_human` to your user rather than reporting success.
      properties:
        status:
          type: string
          enum:
          - human_action_required
        email:
          type: string
          format: email
        message_for_human:
          type: string
          description: Written to be repeated verbatim to the person you are acting for.
        next_step:
          type: object
          properties:
            actor:
              type: string
              enum:
              - human
            action:
              type: string
            why:
              type: string
            fallback_url:
              type: string
              format: uri
        free_credits:
          type: object
          properties:
            amount:
              type: integer
            granted_when:
              type: string
            granted_now:
              type: boolean
              description: Always false here. Credits are released on email confirmation.
            card_required:
              type: boolean
        available_without_an_account:
          type: object
          description: Surfaces usable immediately, so a blocked journey continues instead of stopping.
          additionalProperties:
            type: string
        after_verification:
          type: object
          additionalProperties:
            type: string
        documentation:
          type: string
          format: uri
    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.
  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.