> ## 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.

# Creatorline API

> Generate AI influencer photos and videos, and publish them to social platforms, from your own code.

Creatorline runs AI creators: a persona with a consistent face, voice and audience, posting
on a schedule. The API gives you every piece of that pipeline except the human judgement —
generate media as a specific creator, then publish it to their connected accounts.

Three surfaces, one implementation. They share the same key, the same validation, and the
same credit accounting.

<CardGroup cols={3}>
  <Card title="REST" icon="code" href="/api-reference">
    Your backend, your scripts, anything that speaks HTTP.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    `crl` — terminals, CI, and coding agents.
  </Card>

  <Card title="MCP" icon="robot" href="/mcp">
    Claude Code, Cursor, any MCP client.
  </Card>
</CardGroup>

## Quickstart

<Steps>
  <Step title="Create a key">
    In the studio, go to **Settings → API** and create a key with the `write` scope. The
    key is shown **once** — copy it now.

    ```bash theme={null}
    export CREATORLINE_API_KEY="crl_sk_live_…"
    ```
  </Step>

  <Step title="Check it works">
    ```bash theme={null}
    curl https://api.creatorline.io/v1/me \
      -H "Authorization: Bearer $CREATORLINE_API_KEY"
    ```

    ```json theme={null}
    {
      "object": "account_info",
      "workspace": { "id": "…", "name": "Studio", "plan": "plus", "credit_balance": 4433 },
      "api_key": { "id": "oyYv4L5qhJlH", "name": "Backend", "scope": "write" }
    }
    ```
  </Step>

  <Step title="Generate something">
    ```bash theme={null}
    curl https://api.creatorline.io/v1/generations \
      -H "Authorization: Bearer $CREATORLINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "tool": "text-to-photo",
        "prompt": "matcha latte flatlay on linen, morning light",
        "params": { "aspect_ratio": "4:5" }
      }'
    ```

    Returns immediately with a job handle and the credits it charged:

    ```json theme={null}
    { "object": "generation", "id": "3f6c1a2b-…", "status": "queued",
      "model": "nano-banana-2-text-to-image", "credits_charged": 2, "credit_balance": 4431 }
    ```
  </Step>

  <Step title="Poll until it's done">
    ```bash theme={null}
    curl https://api.creatorline.io/v1/generations/3f6c1a2b-… \
      -H "Authorization: Bearer $CREATORLINE_API_KEY"
    ```

    `queued` → `processing` → `succeeded`, then `output[0].url` is your image.

    <Note>
      Result URLs are time-limited. Download the bytes rather than storing the link.
    </Note>
  </Step>
</Steps>

## The shape of the thing

<AccordionGroup>
  <Accordion title="Generation is asynchronous, always">
    A photo takes \~30 seconds and a video several minutes, so no endpoint blocks on a run.
    You get a job handle and poll it. The run is durable: it survives your process dying,
    and you can rejoin it by id at any time.
  </Accordion>

  <Accordion title="The catalog is the source of truth">
    Do not hardcode model ids or parameter names. [`GET /v1/models`](/api-reference/catalog/list-tools-and-models)
    returns every tool, every model, and the exact inputs and parameters each accepts —
    so a model added to the platform is usable from your code with no change on your side.
  </Accordion>

  <Accordion title="Prices are visible before you pay">
    [`POST /v1/generations/cost`](/api-reference/generations/estimate-a-generation-s-cost)
    prices a run without starting it, using the same function the debit uses. A failed or
    moderation-blocked run is refunded automatically.
  </Accordion>

  <Accordion title="Publishing goes through the review gate">
    A post is created at `pending_review` and publishing is a separate, explicit call. If
    you want a human to approve, simply never call publish — the post waits in the studio's
    review queue. See [Publishing](/publishing).
  </Accordion>
</AccordionGroup>

## What you can do

|                |                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------- |
| **Video**      | UGC video, short clips from a long source, scene replacement, motion sync, burned-in hook captions |
| **Photo**      | text to photo, character-consistent photo editing                                                  |
| **Audio**      | text to speech, lipsync, voice change, dialogue, audio over video                                  |
| **Creators**   | list the workspace's AI creators and generate as one of them                                       |
| **Media**      | browse the library, upload your own images, video and audio                                        |
| **Publishing** | build a post from media and send it to TikTok, Instagram, YouTube or Telegram                      |
| **Billing**    | live credit balance and the full consumption ledger                                                |


## Related topics

- [CLI](/cli.md)
- [Authentication](/authentication.md)
- [MCP server](/mcp.md)
- [Errors and idempotency](/errors.md)
- [Who am I](/api-reference/account/who-am-i.md)