> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraldraft.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate or upload an image

> Two modes — discriminated by the request `Content-Type`:

1. **AI generation** (`application/json`) — kicks off async generation
   inheriting the project's brand context. Returns a [`Job`](#tag/Jobs)
   with `type: image.generate`. On completion, `result` contains
   `{ url, key, width, height }`. Costs **32 credits** (`image`).
2. **Direct upload** (`multipart/form-data`) — synchronous swap with
   the uploaded file bytes. `file` and `key` are required. Returns the
   registered [`Image`](#/components/schemas/Image) immediately. Costs
   **1 credit** (`image_register`). Max 10MB;
   jpg/jpeg/png/webp/gif/svg only.




## OpenAPI

````yaml /openapi.yaml post /images
openapi: 3.1.0
info:
  title: Neural Draft Project API
  version: 1.0.1
  summary: The AI-native backend platform for Lovable / Claude / v0 / Bolt-built sites.
  description: |
    The **Neural Draft Project API** is the single REST contract every AI-built
    site, MCP server tool call, and SDK in our ecosystem speaks against. One
    project key (`ndsk_live_...`) gets you CMS, blog, social, booking and
    commerce primitives behind a stable v1 surface.

    ## Quick start

    ```bash
    curl https://api.neuraldraft.io/v1/projects/me \
      -H "Authorization: Bearer ndsk_live_yourkey"
    ```

    ## Authentication

    Every endpoint except `GET /health` requires a project API key passed as
    `Authorization: Bearer ndsk_live_...`. Keys are scoped to a single project
    (formerly "tenant"). Resolve the project context by calling
    `GET /projects/me`.

    Keys carry one or more **scopes** (e.g. `content:write`, `commerce:admin`).
    A `403 Forbidden` is returned if the key lacks the scope required by the
    endpoint.

    ## Credits

    Most operations cost credits. Costs are documented per endpoint in this
    spec and on the [pricing page](https://neuraldraft.io/pricing). When a
    project has no credits left, every credit-consuming operation returns
    `402 Payment Required` with `code: insufficient_credits`. The response
    includes `cost` (credits the operation needed) and `balance` (credits the
    project had on hand) so clients can render an exact top-up prompt.

    Read-only endpoints (`GET`) do not consume credits. Mutating writes —
    upserting a content key, creating or updating a page, registering an
    image (URL swap or multipart upload) — cost **1 credit** each on top of
    the AI-generation costs documented per endpoint.

    ## Rate limits

    Default project budget is **60 requests per minute**, burst **120**. Every
    response includes:

    | Header | Meaning |
    |---|---|
    | `X-RateLimit-Limit` | Window ceiling |
    | `X-RateLimit-Remaining` | Requests left in window |
    | `X-RateLimit-Reset` | Unix seconds when bucket refills |
    | `Retry-After` | Seconds to wait, only on `429` |

    Enterprise plans get higher budgets — contact sales.

    ## Async work

    Long-running operations (blog generation, image generation, batch
    translation, content plans, full website generation) return a
    [`Job`](#tag/Jobs) resource immediately with `202 Accepted` and
    `status: pending`. Two ways to track progress:

    1. **Poll** `GET /jobs/{id}` until `status` is one of `completed`,
       `failed` or `cancelled`.
    2. **Stream** `GET /jobs/{id}/stream` for a Server-Sent Events feed of
       `progress`, `step`, `done`, `error` events.

    ## Webhooks

    Outgoing webhooks let your project URL receive events (e.g.
    `order.paid`, `blog_post.published`). Manage delivery URLs at
    [`/webhook-endpoints`](#tag/Webhooks). Every delivery is signed with
    HMAC-SHA256:

    ```
    X-Neural-Draft-Signature: t=1745000000,v1=<hex_hmac_sha256(body, secret)>
    X-Neural-Draft-Event: order.paid
    X-Neural-Draft-Delivery: <uuid>
    ```

    Verify the timestamp is within 5 minutes and the HMAC matches before
    trusting the payload.

    ## Idempotency

    Mutating endpoints accept an `Idempotency-Key` header (any unique string
    up to 255 chars). Retries with the same key within 24 hours return the
    original response without re-executing the side effect.

    ## Errors

    All errors follow [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807)
    `application/problem+json` shape. The `code` field is a stable machine
    identifier; the `detail` is a human-readable explanation.
  termsOfService: https://neuraldraft.io/legal/terms
  contact:
    name: Neural Draft Support
    email: info@neuraldraft.io
    url: https://neuraldraft.io/support
  license:
    name: Proprietary
    url: https://neuraldraft.io/legal/api-license
  x-logo:
    url: https://neuraldraft.io/assets/logo-dark.svg
    altText: Neural Draft
servers:
  - url: https://api.neuraldraft.io/v1
    description: Production
  - url: https://api.staging.neuraldraft.io/v1
    description: Staging
security:
  - apiKeyAuth: []
tags:
  - name: Health
    description: Liveness, version, and the runtime OpenAPI document.
  - name: Projects
    description: >
      Project (formerly "tenant") metadata, API key management, and credit
      usage.

      Every API key resolves to exactly one project.
  - name: Brand
    description: |
      Canonical brand context — voice, colors, fonts, audience, content tone.
      This is the single source of truth that the MCP server's `brand://current`
      resource exposes to AI codegen tools.
  - name: Content
    description: |
      The CMS pillar. Translation keys map `dot.notation` keys to per-language
      values. Use `bulk` for build-time fetches of many keys at once.
  - name: Components
    description: >
      Editable HTML chunks registered by AI codegen tools during a build
      session.

      A registered component becomes editable in the project's admin UI.
  - name: Pages
    description: |
      Multi-page authoring with per-page SEO meta (meta_title, meta_description,
      og_*, canonical_url). Pages live alongside the components that render
      them.
  - name: Galleries
    description: |
      Named, ordered image collections. One `slug` per gallery, an `items`
      array of `{url, alt}` (max 200). Updates are full-replace — fetch,
      mutate, send the complete new list back. Use for carousels, lookbooks,
      product galleries, and any other variable-length image set.
  - name: Images
    description: Brand-consistent image generation, replacement, and resolution by key.
  - name: Blog
    description: |
      Full blog engine — posts, categories, tags, scheduling, multi-language
      translation, AI authoring pipeline.
  - name: Social
    description: |
      Social pillar — multi-platform post generation, scheduling, publishing,
      OAuth account connections.
  - name: Booking
    description: |
      Booking pillar — bookable services, weekly availability, slot lookup,
      bookings (admin + public), embeddable widget.
  - name: Commerce
    description: |
      Commerce pillar — products, variants, categories, orders, Stripe
      Checkout, Stripe Connect onboarding, embeddable widgets.
  - name: Jobs
    description: |
      Async work tracking. Every long-running AI op (blog gen, image gen,
      translation, content plan, website gen) returns a Job. Poll or stream.
  - name: Webhooks
    description: |
      Outgoing webhooks. Subscribe a URL to events your project cares about.
      All deliveries signed with HMAC-SHA256.
  - name: Forms
    description: |
      Lead-capture surfaces — newsletter subscribe and contact-form submit.
      Public submit endpoints (no auth, project resolved via
      `X-NeuralDraft-Project-Key` or `?project_id=`); admin list/delete
      endpoints require an API key with `forms:read` / `forms:write` scope.
      No credits charged — this is storage + delivery, not AI.
paths:
  /images:
    post:
      tags:
        - Images
      summary: Generate or upload an image
      description: |
        Two modes — discriminated by the request `Content-Type`:

        1. **AI generation** (`application/json`) — kicks off async generation
           inheriting the project's brand context. Returns a [`Job`](#tag/Jobs)
           with `type: image.generate`. On completion, `result` contains
           `{ url, key, width, height }`. Costs **32 credits** (`image`).
        2. **Direct upload** (`multipart/form-data`) — synchronous swap with
           the uploaded file bytes. `file` and `key` are required. Returns the
           registered [`Image`](#/components/schemas/Image) immediately. Costs
           **1 credit** (`image_register`). Max 10MB;
           jpg/jpeg/png/webp/gif/svg only.
      operationId: createImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerateInput'
            examples:
              hero:
                value:
                  prompt: >-
                    A serene yoga studio at dawn, soft sage and linen tones, no
                    people
                  style: photorealistic
                  aspect_ratio: '16:9'
                  key: hero.background
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - key
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file (jpg/jpeg/png/webp/gif/svg). Max 10MB.
                key:
                  type: string
                  pattern: ^[\w.\-\/]+$
                  example: hero.background
                  description: Stable image key.
      responses:
        '201':
          description: Image uploaded (multipart mode).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Image'
        '202':
          description: Generation job queued (JSON mode).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: Uploaded file exceeds 10MB (multipart mode).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-codeSamples:
        - lang: curl
          label: cURL (AI)
          source: |
            curl -X POST https://api.neuraldraft.io/v1/images \
              -H "Authorization: Bearer ndsk_live_yourkey" \
              -H "Content-Type: application/json" \
              -d '{"prompt":"Serene yoga studio at dawn","style":"photorealistic","aspect_ratio":"16:9","key":"hero.background"}'
        - lang: curl
          label: cURL (upload)
          source: |
            curl -X POST https://api.neuraldraft.io/v1/images \
              -H "Authorization: Bearer ndsk_live_yourkey" \
              -F "file=@hero.jpg" \
              -F "key=hero.background"
        - lang: node
          label: Node (SDK — AI)
          source: >
            const job = await nd.images.generate({ prompt: "Serene yoga studio",
            aspect_ratio: "16:9", key: "hero.background" });

            const done = await nd.jobs.poll(job.id);

            console.log(done.result.url);
        - lang: node
          label: Node (SDK — upload)
          source: |
            const file = await fs.openAsBlob("hero.jpg");
            const img = await nd.images.upload("hero.background", file);
            console.log(img.url);
        - lang: python
          label: Python (AI)
          source: |
            job = requests.post(
                "https://api.neuraldraft.io/v1/images",
                headers={"Authorization": f"Bearer {key}"},
                json={"prompt": "Serene yoga studio", "aspect_ratio": "16:9", "key": "hero.background"},
            ).json()
        - lang: php
          label: PHP
          source: |
            <?php
            $job = json_decode((string) $client->post('images', [
              'headers' => ['Authorization' => 'Bearer '.$key],
              'json' => ['prompt' => 'Serene yoga studio', 'aspect_ratio' => '16:9', 'key' => 'hero.background'],
            ])->getBody(), true);
components:
  schemas:
    ImageGenerateInput:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          example: A serene yoga studio at dawn, soft sage and linen tones, no people
        style:
          type: string
          example: photorealistic
        aspect_ratio:
          type: string
          enum:
            - '1:1'
            - '16:9'
            - '9:16'
            - '4:5'
            - '4:3'
            - '3:2'
          default: '16:9'
        key:
          type: string
          description: Optional. If provided, the image is also addressable by this key.
          example: hero.background
    Image:
      type: object
      required:
        - key
        - url
      properties:
        key:
          type: string
          example: hero.background
        url:
          type:
            - string
            - 'null'
          format: uri
          example: https://cdn.neuraldraft.io/prj_2NfQmBcKpXY8/hero-background-89hf.jpg
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        width:
          type: integer
          example: 2048
        height:
          type: integer
          example: 1152
        bytes:
          type: integer
          example: 482911
        mime_type:
          type: string
          example: image/jpeg
        generated:
          type: boolean
          description: True if produced by AI generation; false if uploaded.
          example: true
    Job:
      type: object
      required:
        - id
        - type
        - status
        - created_at
      properties:
        id:
          type: string
          example: job_2Ngd9KqLmRpW
        type:
          $ref: '#/components/schemas/JobType'
        status:
          $ref: '#/components/schemas/JobStatus'
        progress:
          type: integer
          minimum: 0
          maximum: 100
        message:
          type: string
        steps:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              completed:
                type: boolean
              active:
                type: boolean
        result:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >
            Result payload when `status` is `completed`. Shape depends on
            `type`:


            - `blog_post.generate` → `{ post_id, slug, title }`

            - `social_post.generate` → `{ social_post_id, title, platforms }`

            - `image.generate` → `{ url, key, width, height }`

            - `translation.batch` → `{ keys_translated: int, locales: [string]
            }`
        error:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              example: upstream_unavailable
            message:
              type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      description: |
        RFC 7807 problem+json error. The `code` is a stable machine
        identifier; clients should branch on `code`, never on `title`.
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          type: string
          format: uri
          example: https://api.neuraldraft.io/errors/validation_failed
        title:
          type: string
          example: Validation failed
        status:
          type: integer
          example: 422
        detail:
          type: string
          example: One or more fields failed validation.
        instance:
          type: string
          description: Request id (also returned as `X-Request-Id` header).
          example: req_2Nh4PqRsTuVw
        code:
          type: string
          description: |
            Stable machine error code. Standard values:
            `bad_request`, `unauthorized`, `insufficient_credits`,
            `forbidden`, `not_found`, `conflict`, `validation_failed`,
            `rate_limited`, `internal_error`, `service_unavailable`,
            `slot_unavailable`, `connect_not_ready`, `upstream_unavailable`,
            `idempotency_conflict`.
          example: validation_failed
        cost:
          type: integer
          description: |
            Credits the operation requires. Only present on
            `402 insufficient_credits` responses.
          example: 1
        balance:
          type: integer
          description: |
            Credits the project had on hand at the time of the request.
            Only present on `402 insufficient_credits` responses.
          example: 0
        errors:
          type: object
          description: Field-level validation errors (only on 422).
          additionalProperties:
            type: array
            items:
              type: string
          example:
            customer_email:
              - The customer email field must be a valid email.
            starts_at:
              - The starts at field must be a valid ISO 8601 date.
    JobType:
      type: string
      enum:
        - blog_post.generate
        - social_post.generate
        - image.generate
        - translation.batch
        - content_plan.generate
        - website.generate
    JobStatus:
      type: string
      enum:
        - pending
        - processing
        - completed
        - failed
        - cancelled
  responses:
    BadRequest:
      description: Malformed request — missing required field, invalid JSON, etc.
      headers:
        X-Request-Id:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            bad:
              value:
                type: https://api.neuraldraft.io/errors/bad_request
                title: Bad request
                status: 400
                detail: Request body could not be parsed.
                code: bad_request
                instance: req_2Nh4PqRsTuVw
    Unauthorized:
      description: Missing or invalid API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: '`Bearer realm="Neural Draft"`.'
        X-Request-Id:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              value:
                type: https://api.neuraldraft.io/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: API key missing or invalid.
                code: unauthorized
                instance: req_2Nh4PqRsTuVw
    PaymentRequired:
      description: |
        Insufficient credits. The project does not have enough credits to
        cover the operation. The body includes `cost` (credits the operation
        needs) and `balance` (credits the project had on hand) so clients
        can render an exact top-up prompt. Top up at `/projects/me/usage`
        or wait for the next period to start.
      headers:
        X-Request-Id:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            broke:
              value:
                type: https://neuraldraft.com/errors/payment-required
                title: Payment Required
                status: 402
                detail: This project has no credits remaining for the current period.
                code: insufficient_credits
                cost: 1
                balance: 0
                instance: req_2Nh4PqRsTuVw
    Forbidden:
      description: API key lacks required scope.
      headers:
        X-Request-Id:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            scope:
              value:
                type: https://api.neuraldraft.io/errors/forbidden
                title: Forbidden
                status: 403
                detail: This API key does not have the `commerce:write` scope.
                code: forbidden
                instance: req_2Nh4PqRsTuVw
    ServiceUnavailable:
      description: |
        Temporarily unavailable — typical during Cloud Run cold starts or
        when an upstream AI service is throttling. Safe to retry with
        exponential backoff after `Retry-After` seconds.
      headers:
        Retry-After:
          schema:
            type: integer
        X-Request-Id:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            cold:
              value:
                type: https://api.neuraldraft.io/errors/service_unavailable
                title: Service unavailable
                status: 503
                detail: >-
                  A required upstream service is temporarily unavailable. Retry
                  in 5 seconds.
                code: service_unavailable
                instance: req_2Nh4PqRsTuVw
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        Project API key. Pass as `Authorization: Bearer ndsk_live_...`. Manage
        keys via [`/projects/me/api-keys`](#tag/Projects). Test-mode keys use
        the `ndsk_test_` prefix.

````