AI Content Drop Generation API

openapi: 3.2.0
info:
  title: AI Content Drop Generation 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: generation
  description: Start and poll video/image generations (submit-and-poll)
paths:
  /v1/generate/video:
    post:
      tags:
      - generation
      operationId: generateVideo
      summary: Start a video generation
      description: 'Submits a video generation and returns immediately with status `generating`. Poll GET /v1/videos/{id} (every ~5 seconds) until status is `completed` (video_url populated) or `failed`. Credits are deducted only on success. This endpoint shares its implementation with the website, so safety checks, model fallback, and credit accounting are identical; its error shape is `{"error": ""}`.


        **Async contract:** returns 202 with a `Location` header pointing at the poll URL; poll every ~5 seconds until `status` is `completed` or `failed`. **Idempotency:** send `Idempotency-Key` so a retry cannot double-charge. **Sandbox:** send `X-Sandbox: true` to rehearse without spending credits.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: What to generate, in natural language
                aiModel:
                  type: string
                  description: Model ID from /v1/models (e.g. kling_3_0). Omit to let the platform choose.
                  example: kling_3_0
                duration:
                  type: number
                  description: Clip length in seconds (model-dependent caps apply)
                  default: 5
                aspectRatio:
                  type: string
                  description: 16:9, 9:16, or 1:1
                  default: '16:9'
                style:
                  type: string
                  default: cinematic
                negativePrompt:
                  type: string
                imageUrl:
                  type: string
                  format: uri
                  description: Optional image-to-video conditioning; must be a public https:// URL
                imageRefs:
                  type: array
                  description: Multi-image references for models that support them
                  items:
                    type: object
                    required:
                    - url
                    properties:
                      url:
                        type: string
                        format: uri
                      role:
                        type: string
                        description: e.g. reference_image, first_frame, last_frame
                endFrameUrl:
                  type: string
                  format: uri
                  description: Convenience for a last_frame reference
                quality:
                  type: string
                resolution:
                  type: string
                mode:
                  type: string
      responses:
        '202':
          description: Accepted. Poll GET /v1/videos/{id} until status is completed or failed.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Location:
              description: Absolute URL to poll for this generation
              schema:
                type: string
                format: uri
            Retry-After:
              description: Suggested seconds between polls
              schema:
                type: integer
            Idempotency-Replayed:
              description: Present and `true` when this response was replayed from a previous request with the same Idempotency-Key
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationAccepted'
        '400':
          $ref: '#/components/responses/GenerationBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationError'
        '409':
          description: The Idempotency-Key was already used with a different request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Client-generated unique key (max 200 chars). Retrying with the same key returns the FIRST response instead of starting a second generation, so a dropped connection cannot double-charge. Reusing a key with a different body returns 409.
        schema:
          type: string
          maxLength: 200
        example: a1f3c9e2-7b40-4c1a-9e77-2b1d4c8f0a55
      - name: X-Sandbox
        in: header
        required: false
        description: Set to `true` to validate the request and receive a synthetic completed generation. No provider call, no credits spent, no record created. Use it to rehearse an integration before it costs money.
        schema:
          type: string
          enum:
          - 'true'
      - $ref: '#/components/parameters/SandboxHeader'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      - $ref: '#/components/parameters/SandboxQuery'
  /v1/generate/image:
    post:
      tags:
      - generation
      operationId: generateImage
      summary: Start an image generation
      description: 'Generates an image. Same authentication, billing, and error conventions as video generation. Model IDs come from GET /v1/models?type=image.


        **Async contract:** returns 202 with a `Location` header pointing at the poll URL; poll every ~5 seconds until `status` is `completed` or `failed`. **Idempotency:** send `Idempotency-Key` so a retry cannot double-charge. **Sandbox:** send `X-Sandbox: true` to rehearse without spending credits.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                model:
                  type: string
                  description: Image model ID from /v1/models?type=image
                  example: nano_banana_pro
                negativePrompt:
                  type: string
                imageSize:
                  type: string
                width:
                  type: integer
                height:
                  type: integer
                seed:
                  type: integer
                steps:
                  type: integer
                outputFormat:
                  type: string
                imageUrl:
                  type: string
                  format: uri
                  description: Source image for image-to-image models
                imageUrls:
                  type: array
                  items:
                    type: string
                    format: uri
      responses:
        '202':
          description: Accepted. Poll GET /v1/videos/{id} until status is completed or failed.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Location:
              description: Absolute URL to poll for this generation
              schema:
                type: string
                format: uri
            Retry-After:
              description: Suggested seconds between polls
              schema:
                type: integer
            Idempotency-Replayed:
              description: Present and `true` when this response was replayed from a previous request with the same Idempotency-Key
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationAccepted'
        '400':
          $ref: '#/components/responses/GenerationBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationError'
        '409':
          description: The Idempotency-Key was already used with a different request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Client-generated unique key (max 200 chars). Retrying with the same key returns the FIRST response instead of starting a second generation, so a dropped connection cannot double-charge. Reusing a key with a different body returns 409.
        schema:
          type: string
          maxLength: 200
        example: a1f3c9e2-7b40-4c1a-9e77-2b1d4c8f0a55
      - name: X-Sandbox
        in: header
        required: false
        description: Set to `true` to validate the request and receive a synthetic completed generation. No provider call, no credits spent, no record created. Use it to rehearse an integration before it costs money.
        schema:
          type: string
          enum:
          - 'true'
      - $ref: '#/components/parameters/SandboxHeader'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      - $ref: '#/components/parameters/SandboxQuery'
  /v1/videos:
    get:
      tags:
      - generation
      operationId: listVideos
      summary: List recent generations
      description: Recent video generations for the account, newest first. Page by following `next_cursor` until it is null.
      x-openai-isConsequential: false
      security:
      - ApiKeyAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: 'Opaque cursor from a previous response`s `next_cursor`. Preferred over offset: stable while the list grows.'
        schema:
          type: string
      - name: offset
        in: query
        description: Legacy offset paging. Kept for existing clients; prefer `cursor`, which does not skip or duplicate rows when new generations arrive mid-scan.
        schema:
          type: integer
          minimum: 0
          default: 0
        deprecated: true
      responses:
        '200':
          description: Video list
          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:
                - count
                - videos
                properties:
                  count:
                    type: integer
                  videos:
                    type: array
                    items:
                      $ref: '#/components/schemas/Video'
                  has_more:
                    type: boolean
                    description: Whether another page exists
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Pass as `cursor` to fetch the next page; null at the end
                  next_url:
                    type:
                    - string
                    - 'null'
                    format: uri
                    description: Ready-made URL for the next page
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/videos/{id}:
    get:
      tags:
      - generation
      operationId: getVideo
      summary: Poll a generation
      description: The polling half of submit-and-poll. status moves generating → completed (video_url populated) or → failed (error_message populated). Videos owned by other accounts read as 404.
      x-openai-isConsequential: false
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Video record
          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/Video'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    GenerationError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message
        code:
          type: string
          description: Optional machine-readable code, e.g. INVALID_BILLING_MODE
      description: Error shape of the generation endpoints (shared with the website UI).
    GenerationAccepted:
      type: object
      required:
      - video
      description: 202 from either generation endpoint. `video` carries the job for images too — one shape across both so a client needs one parser.
      properties:
        sandbox:
          type: boolean
          description: 'true when X-Sandbox: true was sent. Nothing was generated and no credits were spent.'
        video:
          $ref: '#/components/schemas/GenerationJob'
    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
    Video:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
        status:
          type: string
          description: generating | completed | failed | timeout
        title:
          type:
          - string
          - 'null'
        model:
          type:
          - string
          - 'null'
        prompt:
          type:
          - string
          - 'null'
        duration:
          type:
          - number
          - 'null'
        aspect_ratio:
          type:
          - string
          - 'null'
        credits_used:
          type: number
        video_url:
          type:
          - string
          - 'null'
          format: uri
          description: Populated when status is completed
        thumbnail_url:
          type:
          - string
          - 'null'
          format: uri
        error_message:
          type:
          - string
          - 'null'
          description: Populated when status is failed
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    GenerationJob:
      type: object
      required:
      - id
      - status
      description: 'A submitted generation. Submit-and-poll: this is the acknowledgement, not the result. Poll GET /v1/videos/{id} until status is completed or failed.'
      properties:
        id:
          type: string
          description: Poll this id. A sandbox job is prefixed `sandbox_`.
        title:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - generating
          - completed
          - failed
          - timeout
        aiModel:
          type:
          - string
          - 'null'
          description: Normalised model id the job was routed to.
        creditsUsed:
          type: number
          description: '0 at submission. Billing is post-deduct: credits are charged only when the generation succeeds.'
        videoUrl:
          type:
          - string
          - 'null'
          format: uri
        imageUrl:
          type:
          - string
          - 'null'
          format: uri
        note:
          type:
          - string
          - 'null'
  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:
    GenerationBadRequest:
      description: Invalid request (missing prompt, bad imageUrl, unknown model, …)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationError'
    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'
    NotFound:
      description: No such resource (or not owned by this account)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    SandboxQuery:
      name: sandbox
      in: query
      required: false
      description: Query-parameter form of the X-Sandbox header, for clients that cannot set headers.
      schema:
        type: string
        enum:
        - 'true'
    SandboxHeader:
      name: X-Sandbox
      in: header
      required: false
      description: 'Send `true` to rehearse this call. Returns a synthetic completed generation: no provider call, no credits, no history row. Validation still runs. Works without an API key, so the response shape is observable before a credential exists. Documented at https://aicontentdrop.com/docs/sandbox.'
      schema:
        type: string
        enum:
        - 'true'
        - '1'
      example: 'true'
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: Client-generated key (max 200 characters). A retry with the same key returns the FIRST response instead of starting a second generation. The same key with a different body is a 409. Keys are retained 24 hours.
      schema:
        type: string
        maxLength: 200
      example: 9f1c2b7e-0f2a-4e0b-9a1e-3c9f5d2b7a10
  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.