AI Content Drop Account API

openapi: 3.2.0
info:
  title: AI Content Drop Account 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: Account
  description: API-key identity and credit balance
paths:
  /v1/me:
    get:
      tags:
      - Account
      operationId: getAccount
      summary: Account and credit balance
      description: Identity, plan, and remaining credits for the account that owns the API key, plus the key's own name, scopes, and optional daily credit ceiling. The first call every integration should make — it verifies the key and tells you how much budget is available.
      x-openai-isConsequential: false
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Account details
          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:
                - id
                - credits
                - plan
                properties:
                  id:
                    type: string
                    format: uuid
                  username:
                    type:
                    - string
                    - 'null'
                  email:
                    type:
                    - string
                    - 'null'
                    format: email
                  credits:
                    type: number
                    description: Remaining credit balance
                  plan:
                    type:
                    - string
                    - 'null'
                    description: free | starter | professional | ultra | enterprise_max
                  api_key:
                    type: object
                    properties:
                      name:
                        type:
                        - string
                        - 'null'
                      scopes:
                        type: array
                        items:
                          type: string
                      daily_credit_limit:
                        type:
                        - integer
                        - 'null'
                        description: Max credits this key may spend per UTC day; null = unlimited
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /agent/auth/register:
    post:
      tags:
      - Account
      operationId: registerAgent
      summary: Register an agent for a read-scoped token
      description: Self-registration for unattended agents (WorkOS auth.md `agent_auth`, identity type `anonymous`). Returns a client_id/client_secret and an immediately usable read-scoped bearer token. The token only raises rate limits on the public read surface — it cannot generate, spend credits, or read an account. Generation needs an `acd_live_` key created by a signed-in human.
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                  maxLength: 80
                  description: How you want to be identified in our logs
                identity_type:
                  type: string
                  enum:
                  - anonymous
      responses:
        '201':
          description: Registered. The response already contains a usable read-scope bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRegistration'
        '400':
          description: Unsupported identity_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /agent/auth/claim:
    post:
      tags:
      - Account
      operationId: claimAgentToken
      summary: Exchange client credentials for a fresh token
      description: Trade the client_id and client_secret from registration for a new 24-hour read-scoped bearer token. Use this when a token expires rather than registering again.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - client_id
              - client_secret
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
      responses:
        '200':
          description: A refreshed read-scope bearer token for an existing client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTokenClaim'
        '401':
          description: Unknown client_id or wrong client_secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /agent/auth/revoke:
    post:
      tags:
      - Account
      operationId: revokeAgentToken
      summary: Revoke an agent token
      description: Invalidate a read-scoped agent token immediately. Per RFC 7009, revoking an already-invalid token is a success, not an error.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: boolean
        '400':
          description: No token supplied
          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:
    AgentTokenClaim:
      type: object
      required:
      - access_token
      - token_type
      - expires_in
      - scope
      description: 200 from POST /agent/auth/claim — a refreshed token for an already-registered client.
      properties:
        access_token:
          type: string
        token_type:
          type: string
          enum:
          - Bearer
        expires_in:
          type: integer
        expires_at:
          type: integer
        scope:
          type: string
          enum:
          - read
        documentation:
          type: string
          format: uri
    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
    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.
    AgentRegistration:
      type: object
      required:
      - client_id
      - access_token
      - token_type
      - expires_in
      - scope
      description: 201 from POST /agent/auth/register. One unauthenticated call returns a usable read-scope bearer token — no email, no human, no approval.
      properties:
        client_id:
          type: string
        client_secret:
          type: string
          description: Shown once. Needed only to claim the client against a real account later.
        client_name:
          type: string
        identity_type:
          type: string
          enum:
          - anonymous
        access_token:
          type: string
          description: 'Send as `Authorization: Bearer <token>`.'
        token_type:
          type: string
          enum:
          - Bearer
        expires_in:
          type: integer
          description: Seconds until expiry (86400).
        expires_at:
          type: integer
          description: Unix seconds.
        scope:
          type: string
          enum:
          - read
          description: Read only. This token cannot spend credits.
        claim_uri:
          type: string
          format: uri
        revocation_uri:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        note:
          type: string
  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:
    Unauthorized:
      description: Missing, malformed, revoked, or budget-exhausted API key
      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'
  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.