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

# Start a generation

> Start an image or video run. **This is the API's one paid operation** and it is
asynchronous by design: a video takes minutes, so the call returns a job handle
immediately and you poll `GET /v1/generations/{id}`.

`inputs` values are either an asset id or a public `https` URL (adopted as an asset
automatically). `params` are validated against the model's own schema — an unknown key
is a 400, never a silent drop, because a silently ignored parameter on a paid call is
the worst possible outcome.

Send `Idempotency-Key` and a retry returns the ORIGINAL generation instead of paying
for a second run.



## OpenAPI

````yaml /openapi.json post /v1/generations
openapi: 3.1.0
info:
  title: Creatorline API
  version: 1.0.0
  description: >-
    Generate AI influencer photos and videos, and publish them to your creators'
    social

    accounts — from your own backend, your scripts, or a coding agent.


    Every request authenticates with an organization-scoped API key and is
    charged against

    that organization's credits, at the same prices the studio shows.
servers:
  - url: https://api.creatorline.io
    description: Production
  - url: http://localhost:3000/api
    description: Local development (the same routes, under the app's own /api prefix)
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Account
    description: Who the key belongs to, and what it can spend.
  - name: Catalog
    description: The live tool and model catalog. Read it, do not hardcode it.
  - name: Creators
    description: The AI creators a generation or post belongs to.
  - name: Generations
    description: Start, price and poll image and video runs.
  - name: Assets
    description: The media library, and uploading your own files.
  - name: Posts
    description: Turn media into a post and publish it to social platforms.
  - name: Credits
    description: Balance and the consumption ledger.
paths:
  /v1/generations:
    post:
      tags:
        - Generations
      summary: Start a generation
      description: >-
        Start an image or video run. **This is the API's one paid operation**
        and it is

        asynchronous by design: a video takes minutes, so the call returns a job
        handle

        immediately and you poll `GET /v1/generations/{id}`.


        `inputs` values are either an asset id or a public `https` URL (adopted
        as an asset

        automatically). `params` are validated against the model's own schema —
        an unknown key

        is a 400, never a silent drop, because a silently ignored parameter on a
        paid call is

        the worst possible outcome.


        Send `Idempotency-Key` and a retry returns the ORIGINAL generation
        instead of paying

        for a second run.
      operationId: createGeneration
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            A UUID you generate. A replay returns the original generation with
            `idempotent-replay: true`. Keys are namespaced per API key and kept
            for 24 hours.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGenerationRequest'
            examples:
              photo:
                summary: A photo from a prompt
                value:
                  tool: text-to-photo
                  prompt: matcha latte flatlay on a linen tablecloth, morning light
                  params:
                    aspect_ratio: '4:5'
                    resolution: 2K
              video:
                summary: A UGC video for one creator, from a reference image
                value:
                  tool: ugc-video
                  prompt: unboxing a skincare set, chatty and warm
                  account_id: e307923d-bc66-4959-a297-6e230b93dc22
                  inputs:
                    characters:
                      - https://example.com/face.png
                  params:
                    aspect_ratio: '9:16'
                    duration: '5'
      responses:
        '200':
          description: >-
            An idempotent replay: the original generation, unchanged and not
            re-charged.
          headers:
            x-request-id:
              description: >-
                Correlation id for this request. Quote it in any support
                question.
              schema:
                type: string
            x-ratelimit-limit:
              description: Requests allowed per minute.
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            x-ratelimit-reset:
              description: Unix seconds when the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
        '202':
          description: Accepted. The run is queued; poll it by id.
          headers:
            x-request-id:
              description: >-
                Correlation id for this request. Quote it in any support
                question.
              schema:
                type: string
            x-ratelimit-limit:
              description: Requests allowed per minute.
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            x-ratelimit-reset:
              description: Unix seconds when the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationAccepted'
              example:
                object: generation
                id: 3f6c1a2b-8d4e-4c11-9a77-2b8f0e5d1c93
                status: queued
                tool: ugc-video
                stage: video-ref
                model: bytedance-seedance-2-0-reference-to-video-fast
                count: 1
                ratio: '9:16'
                file_type: video
                credits_charged: 30
                credit_balance: 4403
                output: []
        '400':
          description: Invalid request. `param` names the offending field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: invalid_request_error
                  code: invalid_parameter
                  message: >-
                    Invalid value for "aspect_ratio": "99:99". Allowed: 1:1,
                    9:16, 16:9.
                  param: params.aspect_ratio
                request_id: req_8fQ2mRxK1pLd
        '401':
          description: Missing, malformed, revoked or expired key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: Missing or invalid API key.
                request_id: req_8fQ2mRxK1pLd
        '402':
          description: The workspace cannot cover this run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: insufficient_credits_error
                  code: insufficient_credits
                  message: This request costs 30 credits and the workspace has 12.
                request_id: req_8fQ2mRxK1pLd
                required_credits: 30
                credit_balance: 12
        '403':
          description: The key exists but may not do this (read-only key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: permission_error
                  code: insufficient_scope
                  message: >-
                    This API key is read-only. Create a key with the `write`
                    scope to run generations.
                request_id: req_8fQ2mRxK1pLd
        '404':
          description: No such resource — including one that belongs to another workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: not_found_error
                  code: resource_missing
                  message: No such generation.
                request_id: req_8fQ2mRxK1pLd
        '429':
          description: Too many requests. Honour `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  message: Too many requests. Slow down and retry.
                request_id: req_8fQ2mRxK1pLd
components:
  schemas:
    CreateGenerationRequest:
      type: object
      properties:
        tool:
          type: string
          enum:
            - ugc-video
            - short-clip
            - scene-video
            - motion-control
            - hook-captions
            - photo-edit
            - text-to-photo
            - add-audio
            - lipsync
            - change-voice
            - text-to-speech
            - dialogue
          description: The tool to run. Preferred over `stage`.
        stage:
          type: string
          description: Lower-level escape hatch when you want to address a stage directly.
        model:
          type: string
          enum:
            - nano-banana-pro
            - nano-banana-2-text-to-image
            - gpt-image-v2-text-to-image
            - nano-banana-pro-edit
            - nano-banana-2-edit
            - bytedance-seedream-v4-5-edit
            - gpt-image-v2-edit
            - bytedance-seedance-2-0-image-to-video
            - bytedance-seedance-2-0-image-to-video-fast
            - xai-grok-imagine-video-1-5-preview-image-to-video
            - google-gemini-omni-flash-image-to-video
            - bytedance-seedance-2-0-reference-to-video
            - bytedance-seedance-2-0-mini-reference-to-video
            - bytedance-seedance-2-0-reference-to-video-fast
            - xai-grok-imagine-reference-to-video
            - google-gemini-omni-flash-reference-to-video
            - kling-v3-standard-motion-control
            - hook-write
            - caption-burn
            - short-clip
            - bytedance-seedance-2-0-text-to-video
            - sync-3-lipsync
            - sync-lipsync-v2-pro
            - ffmpeg-api-merge-audio-video
            - elevenlabs-zrm-text-to-speech
            - elevenlabs-zrm-text-to-dialogue
            - change-voice
            - scene-seedance-2-0
            - scene-seedance-2-0-mini
            - scene-kling-o3-pro-reference
            - scene-seedance-2-0-fast
            - scene-kling-o3-standard-reference
            - scene-kling-o3-pro-edit
            - scene-kling-o3-standard-edit
          description: Override the tool's default model. Must belong to the tool's stage.
        prompt:
          type: string
          description: What to create. Required by most models.
        account_id:
          type: string
          format: uuid
          description: Generate as this creator — inherits their look, voice and persona.
        inputs:
          type: object
          description: >-
            Slot key → asset id(s) or public https URL(s), per the model's
            `inputs`. A URL is adopted as an asset automatically.
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
        params:
          type: object
          description: >-
            Model parameters. Validated against the model's schema — an unknown
            key is a 400.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
        count:
          type: integer
          minimum: 1
          maximum: 4
          description: >-
            Alternatives to produce. Image models only; video is always one
            take.
    Generation:
      type: object
      properties:
        object:
          type: string
          enum:
            - generation
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
        tool:
          type: string
        stage:
          type: string
        model:
          type: string
        prompt:
          type: string
        params:
          type: object
          additionalProperties: true
        account_id:
          type: string
          format: uuid
        error:
          type: string
          description: Present on `failed`. The credits were refunded.
        created_at:
          type: number
        updated_at:
          type: number
        output:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
      required:
        - object
        - id
        - status
        - output
    GenerationAccepted:
      allOf:
        - $ref: '#/components/schemas/Generation'
        - type: object
          properties:
            credits_charged:
              type: number
            credit_balance:
              type: number
            count:
              type: integer
            ratio:
              type: string
            file_type:
              type: string
              enum:
                - image
                - video
                - audio
    Error:
      type: object
      description: >-
        Every failure has this shape. `param` names the offending field when
        there is one.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - not_found_error
                - rate_limit_error
                - insufficient_credits_error
                - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
          required:
            - type
            - code
            - message
        request_id:
          type: string
        required_credits:
          type: number
          description: 402 only.
        credit_balance:
          type: number
          description: 402 only.
      required:
        - error
        - request_id
    Asset:
      type: object
      properties:
        object:
          type: string
          enum:
            - asset
        id:
          type: string
          format: uuid
        type:
          type: string
        file_type:
          type: string
          enum:
            - image
            - video
            - audio
        title:
          type: string
        ratio:
          type: string
        duration_sec:
          type: number
        url:
          type: string
          format: uri
          description: >-
            Fetchable media URL. TIME-LIMITED for stored objects — download, do
            not cache.
        thumbnail_url:
          type: string
          format: uri
        mime_type:
          type: string
        size_bytes:
          type: number
        source:
          type: string
        status:
          type: string
        tool:
          type: string
        account_id:
          type: string
          format: uuid
      required:
        - object
        - id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your organization's API key, from Settings → API. `Authorization: Bearer
        crl_sk_live_…`
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to the Authorization header, for tooling that prefers it.

````

## Related topics

- [Start an upload](/api-reference/assets/start-an-upload.md)
- [Errors and idempotency](/errors.md)
- [Creatorline API](/index.md)
- [MCP server](/mcp.md)
- [Authentication](/authentication.md)