# Image Agent 1
Source: https://docs.tokenkit.co/api-reference/agents/image-agent-1

POST /v2/image/agent
Run image-agent-1 with text instructions and optional reference images. Currently in early access preview.

## Request body

`multipart/form-data` (recommended when sending images)

* `model_id` (`validImageModelIds`, optional): Defaults to `"image-agent-1-preview"`
* `agent_id` (`string`, optional)
* `instructions` (`string`, required): Between `3` and `10,000` characters
* `aspect_ratio` (`"auto" | validAspectRatios`, optional): Defaults to `"1:1"`
* `resolution` (`validResolutions`, optional): Defaults to `"2K"`
* `images` (`file | file[]`, optional): Single image or up to `10` images, each max `30MB`; defaults to `[]`
* `webhook_url` (`string`, optional): Must be a valid URL
* `max_steps` (`number`, optional): Minimum `1`, maximum `30`, defaults to `10`

## Validation rules

* `instructions` minimum length: `3`
* `instructions` maximum length: `10,000`
* `images` accepts either:
  * a single image
  * an array of images (max `10`)
* `images` is normalized to an array internally


# Overview
Source: https://docs.tokenkit.co/api-reference/jobs/overview

Learn how TokenKit's async job system works and how to monitor progress

Most TokenKit operations are asynchronous. When you make a request to an endpoint, the API immediately returns a **job ID** and processes your request in the background.

## Why async?

AI model processing can take anywhere from a few seconds to several minutes depending on:

* Model complexity and the specific endpoint
* Request parameters and input size
* Current system load
* Processing requirements

Rather than keeping your HTTP connection open, TokenKit follows an async pattern that lets you:

* Submit multiple jobs in parallel
* Check status at your own pace
* Stream real-time progress updates
* Build responsive UIs that don't block

## Job lifecycle

Every job moves through a series of states:

```mermaid theme={null}
graph LR
    A[queued] --> B[processing]
    B --> C[succeeded]
    B --> D[failed]
```

| State        | Description                                           |
| ------------ | ----------------------------------------------------- |
| `queued`     | Job is queued but not yet started                     |
| `processing` | Actively processing your request                      |
| `succeeded`  | Completed successfully; outputs are ready             |
| `failed`     | Encountered an error; check `error` field for details |

## Checking job status

### Polling with GET /jobs/:id

The simplest approach is to poll the job endpoint until it reaches a terminal state:

```bash theme={null}
curl -H "Authorization: Bearer $TOKENKIT_API_KEY" \
  https://api.tokenkit.co/v1/jobs/job_abc123
```

**Response example:**

```json theme={null}
{
  "data": {
    "status": "processing",
    "created_at": "2025-10-21T10:30:00Z",
    "outputs": null,
    "error": null
  },
  "errors": null
}
```

**When succeeded:**

```json theme={null}
{
  "data": {
    "id": "job_abc123",
    "status": "succeeded",
    "progress": 1.0,
    "outputs": {
      "results": [
        {
          "url": "https://static.tokenkit.co/.../output_1.png"
        },
        {
          "url": "https://static.tokenkit.co/.../output_2.png"
        }
      ]
    },
    "error": null
  },
  "errors": null
}
```

<Info>
  **Polling best practices:**

  * Start with 2-3 second intervals
  * Use exponential backoff (double the interval after each check)
  * Max out at 30-60 second intervals for long jobs
  * Stop polling once status is `succeeded` or `failed`
</Info>

### Streaming with GET /jobs/:id/stream

For real-time updates, use Server-Sent Events (SSE) streaming:

```bash theme={null}
curl -N -H "Authorization: Bearer $TOKENKIT_API_KEY" \
  https://api.tokenkit.co/v1/jobs/job_abc123/stream
```

The stream emits events as the job progresses:

```
event: status
data: {"status":"processing","output":null}

event: log
data: {"level":"info","message":"Processing input","created_at":"2025-10-21T10:30:05Z"}

event: log
data: {"level":"info","message":"Running model inference","created_at":"2025-10-21T10:30:12Z"}

event: result
data: {"images":[{"w256":"https://static.tokenkit.co/.../output_1_w256.png","w512":"https://static.tokenkit.co/.../output_1_w512.png","w1024":"https://static.tokenkit.co/.../output_1_w1024.png","full":"https://static.tokenkit.co/.../output_1.png"}],"request_duration_s":45,"model_id":"portrait-1-pro","style_id":123}

event: end
data: succeeded
```

**Event types:**

| Event    | Description                                           |
| -------- | ----------------------------------------------------- |
| `status` | Job state changed; includes `progress` (0.0-1.0)      |
| `log`    | Human-readable progress message                       |
| `result` | Output is ready (for endpoints with multiple results) |
| `end`    | Job reached terminal state (`succeeded` or `failed`)  |

<Tip>
  Streaming is ideal for:

  * Incremental result delivery for batch operations
  * Real-time log displays
</Tip>


# Job
Source: https://docs.tokenkit.co/api-reference/jobs/retrieve

GET /v1/jobs/{job_id}
Fetch the latest status and result of a job

Returns the job metadata, input payload, current output (if any), and navigational links.

## Path parameters

* `job_id`: UUID returned by any write endpoint

## Example

```bash theme={null}
curl -H "Authorization: Bearer $TOKENKIT_API_KEY" \
  https://api.tokenkit.co/v1/jobs/job_123
```

```json theme={null}
{
    "data": {
        "type": "portrait",
        "status": "processing",
        "created_at": "2025-10-27T09:05:26.074Z",
        "input": {},
        "output": null,
        "errors": null,
        "links": {
            "self": "/v1/jobs/4ea6bae9-2efe-4d12-bc8e-23bb6c1e3366",
            "stream": "/v1/jobs/4ea6bae9-2efe-4d12-bc8e-23bb6c1e3366/stream"
        }
    },
    "errors": null
}
```

## Error codes

* `JOB_ID_REQUIRED`: missing job ID
* `JOB_NOT_FOUND`: the job does not exist or was not made by your api key

When encountering unexpected issues, the API returns `500` with `INTERNAL_ERROR` and includes the message in the error payload.


# Stream Job
Source: https://docs.tokenkit.co/api-reference/jobs/stream

GET /v1/jobs/{job_id}/stream
Receive live job updates via Server-Sent Events

Establishes an SSE connection that emits job updates until completion. Useful for real-time dashboards or CLI workflows.

## Example

```bash theme={null}
curl -N -H "Authorization: Bearer $TOKENKIT_API_KEY" \
  https://api.tokenkit.co/v1/jobs/job_123/stream
```

## Event types

* `status`: initial state (`queued`, `processing`, etc.)
* `log`: operational messages
* `result`: final job output (mirrors the `output` field from the polling endpoint)
* `error`: error string when the job fails
* `end`: terminal state (`succeeded` or `failed`)
* `ping`: keep-alive heartbeat every 15 seconds

## Headers

TokenKit sets SSE-friendly headers to prevent caching:

```
Cache-Control: no-cache, no-transform
X-Accel-Buffering: no
Connection: keep-alive
```

Clients may resume streams by supplying `Last-Event-ID`. The server tracks log IDs to avoid replaying old entries.

## Errors

* Missing job ID or invalid credential -> `400`/`401`
* Unknown job for the current client -> `404`

When an error occurs, the stream emits an `error` event and closes with `end: failed`.


# Webhooks
Source: https://docs.tokenkit.co/api-reference/jobs/webhooks

Get async job completion updates through your own HTTPS endpoint

Some async endpoints support optional webhook delivery. When supported, the request body includes a `webhook_url` field.

If an endpoint does not show `webhook_url` in its request body schema, webhooks are not available for that endpoint.

## How to enable

For supported endpoints, include your HTTPS URL in `webhook_url` when creating the job:

```json theme={null}
{
  "input": {
    "...": "..."
  },
  "webhook_url": "https://your-app.com/webhooks/tokenkit"
}
```

## Delivery behavior

When a job reaches a terminal state, TokenKit sends a `POST` request to your `webhook_url` with JSON:

```json theme={null}
{
  "job_id": "job_abc123",
  "status": "succeeded",
  "data": {
    "...": "endpoint-specific output"
  }
}
```

* `status` is `succeeded` or `failed`
* `data` contains the final job result or failure payload for that endpoint

## Reliability and retry logic

Webhook delivery uses fire-and-forget semantics so your original API request is never blocked by webhook failures:

* Only `https://` URLs are allowed; non-HTTPS URLs are skipped
* Request method is `POST` with `Content-Type: application/json`
* Each attempt has a 10 second timeout
* Non-2xx responses are treated as failures and retried
* Up to 5 total attempts are made (initial try + 4 retries)
* Retries use exponential backoff starting at 1 second (1s, 2s, 4s, 8s)

## Implementation notes

* Return a fast `2xx` response from your webhook handler to avoid unnecessary retries
* Design your endpoint to be idempotent in case of repeated delivery attempts


# Character Image Sheet
Source: https://docs.tokenkit.co/api-reference/tools/character-image-sheet

POST /v2/image-utils/character-image-sheet
Generates a multi-pose character sheet from one prompt or reference image

## Request body

`multipart/form-data`

* `character_image` (`file`, optional): Character image input, max `15MB`
* `character_prompt` (`string`, optional): Text prompt to define the character
* `webhook_url` (`string`, optional): Must be a valid URL
* `resolution` (`"2K" | "4K"`, optional): Defaults to `"2K"`

## Validation rules

* You must provide at least one of:
  * `character_image`
  * `character_prompt`
* If both are missing, validation fails with:
  * `"Must provide character_image or character_prompt."`


# Detail Preservation
Source: https://docs.tokenkit.co/api-reference/tools/detail-preservation

POST /v2/image-utils/detail-preservation
Repairs incorrect details in AI-generated images

## Request body

`multipart/form-data`

* `source_image` (`file`, required): Source image, max `30MB`
* `reference_images` (`file | file[]`, required): One or more reference images, each max `30MB`

## Validation rules

* `reference_images` accepts either:
  * a single image
  * an array of images
* Input is normalized to an array internally
* At least one reference image is required:
  * `"reference_images must contain at least 1 image"`


# Extract SVG Icon
Source: https://docs.tokenkit.co/api-reference/tools/extract-svg-icon

POST /v2/image-utils/extract-svg-icon
Extracts an SVG icon from an input image

## Request body

`multipart/form-data`

* `image` (`file | string`, required): Uploaded image or image URL, max `15MB` for uploads

## Validation rules

* `image` is required


# Image Web Search
Source: https://docs.tokenkit.co/api-reference/tools/image-web-search

POST /v2/image-utils/image-web-search
Finds the best web image match from a semantic query

## Request body

`application/json` (or form body, depending on your client setup)

* `instructions` (`string`, required): Between `3` and `10,000` characters
* `aspect_ratio` (`"any" | validAspectRatios`, optional): Defaults to `"any"`
* `effort` (`"high" | "low"`, optional): Defaults to `"low"`

## Validation rules

* `instructions` minimum length: `3`
* `instructions` maximum length: `10,000`


# Prompt Enhancer
Source: https://docs.tokenkit.co/api-reference/tools/prompt-enhancer

POST /v2/image-utils/prompt-enhancer
Rewrites and expands text prompts for clearer, higher-quality results

## Request body

`multipart/form-data` (recommended when sending images)

* `instructions` (`string`, required): Between `3` and `10,000` characters
* `aspect_ratio` (`validAspectRatios`, optional)
* `effort` (`"high" | "low"`, optional): Defaults to `"high"`
* `images` (`file | file[]`, optional): Single image or up to `10` images, each max `30MB`

## Validation rules

* `images` accepts either:
  * a single image
  * an array of images (max `10`)
* Input is normalized to an array internally when provided


# Authentication & API Keys
Source: https://docs.tokenkit.co/authentication

Secure your API requests with Bearer token authentication

TokenKit uses API keys to authenticate requests. All requests must include a valid Bearer token in the `Authorization` header.

## Getting your API key

1. Sign in to the [Platform](https://www.tokenkit.co/platform/api-keys)
2. Navigate to **API Keys**
3. Click **Create API Key**
4. Copy the generated key (starts with `sk_live_v1...`)

<Warning>
  Your API key carries all privileges for your account. Never share it publicly or commit it to version control. If a key is compromised, delete it immediately from the dashboard.
</Warning>

## Making authenticated requests

Include your API key in the `Authorization` header with the `Bearer` scheme:

```bash theme={null}
curl https://api.tokenkit.co/v1/endpoint \
  -H "Authorization: Bearer sk_live_v1_your_key_here"
```

## Authentication errors

### Missing or invalid token

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "Invalid or missing Bearer token"
    }
  ]
}
```

**Common causes:**

* Forgot to include the `Authorization` header
* Typo in the API key
* Using a revoked or deleted key
* Missing `Bearer` prefix

## Managing API keys

All API key management happens through the **platform**. You can create and delete keys at any time.

Go to the [platform](https://www.tokenkit.co/platform/api-keys) to:

* **Create new API keys** - Generate additional keys for different projects or environments
* **View existing keys** - See all your active API keys
* **Delete keys** - Permanently revoke keys that are no longer needed

<Card title="Customer Platform" icon="square-terminal" href="https://www.tokenkit.co/platform/api-keys">
  Manage your API keys and monitor authentication activity
</Card>


# Credits & Pricing
Source: https://docs.tokenkit.co/credits-pricing

Understand TokenKit's credit-based pricing model and how to manage your account

## How Credits Work

TokenKit uses a **pay-as-you-go credit system** to ensure transparent and predictable billing:

### Credit Consumption

* **Purchase credits upfront** - Load your account with credits before making API requests
* **Charged per successful job** - Credits are only deducted when a job completes successfully
* **Unit cost varies by endpoint** - Different agent and tools have different credit costs

<Warning>
  Keep an eye on your credit balance to avoid service interruptions. If you are out of credits, your requests will be denied.
</Warning>

## Pricing

For up-to-date pricing information, visit our pricing page:

<Card title="View Pricing" icon="tag" href="https://www.tokenkit.co/pricing">
  See current credit packages, rates, and volume discounts
</Card>

## Managing Credits & Billing

All credit and payment management happens through the [Platform](https://www.tokenkit.co/platform)

### Access The Customer Platform

Go to the [platform](https://www.tokenkit.co/platform) to:

* **View your current balance** - See available credits in real-time
* **Purchase additional credits** - Buy more credits when you need them
* **Track your spending** - Monitor credit consumption across all your jobs

<Card title="Customer Platform" icon="square-terminal" href="https://www.tokenkit.co/platform">
  Access your account to manage credits, view usage analytics, and handle all billing
</Card>


# Introduction
Source: https://docs.tokenkit.co/index

Access specialized AI models designed for specific use cases through a developer-friendly REST API

<img alt="Hero Light" />

<img alt="Hero Dark" />

## What is TokenKit?

TokenKit is an applied AI lab focused on agentic image generation. We build agents and tools on top of leading foundation models, helping businesses unlock custom capabilities through tailored solutions while also offering general-purpose API access for developers.

## Key Features

* **Agentic Image Generation** - Agents and tools built on top of state-of-the-art models for real-world image use cases
* **Simple REST API** - Straightforward HTTP requests with JSON responses
* **Asynchronous Processing** - All jobs are processed asynchronously with real-time status updates
* **Credit-Based Pricing** - Pay only for what you use with transparent, per-request pricing
* **Production Ready** - Built for scale with rate limiting, error handling, and comprehensive documentation

## Getting Started

Everything you need to start making requests to TokenKit:

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API request in minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys and securing your requests
  </Card>

  <Card title="Credits & Pricing" icon="credit-card" href="/credits-pricing">
    Understand the credit system and pricing
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/usage-limits">
    Learn about request limits and how to manage them
  </Card>
</CardGroup>

## API Essentials

### Base URL

All API endpoints use the following base URL:

```bash theme={null}
https://api.tokenkit.co/v2
```

### Authentication

Include your API key in the `Authorization` header with the `Bearer` scheme:

```http theme={null}
Authorization: Bearer sk_live_v1_your_key_here
```

### Response Format

All API responses follow a consistent envelope structure:

```json theme={null}
{
  "data": {
    // Response payload
  },
  "errors": null
}
```

When errors occur, the response includes error details:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human-readable error message"
    }
  ]
}
```


# Quickstart
Source: https://docs.tokenkit.co/quickstart

Send your first request to TokenKit in minutes

<Steps>
  <Step title="Create an Account">
    Sign up for a TokenKit [Platform](https://www.tokenkit.co/platform) account. You'll get access to your dashboard where you can manage API keys, credits, and usage.
  </Step>

  <Step title="Get Your API Key">
    Navigate to the [API Keys section](https://www.tokenkit.co/platform/api-keys) in your dashboard and create your first API key. Copy the key - it starts with `sk_live_v1...` and you'll need it for authentication.
  </Step>

  <Step title="Buy Credits">
    Before making requests, you'll need credits in your account. Visit the [pricing page](https://www.tokenkit.co/pricing) to see current pricing, then click "Buy Credits" in the platform to purchase credits.
  </Step>

  <Step title="Send a POST Request">
    Choose an endpoint and send a request with your API key:

    ```bash theme={null}
    curl -X POST https://api.tokenkit.co/v2/image-utils/detail-preservation \
      -H "Authorization: Bearer sk_live_v1_your_key_here" \
    ```

    The API will return a job ID:

    ```json theme={null}
    {
        "data": {
            "job_id": "job_abc123xyz",
            "links": {
                "job": "/v1/jobs/job_abc123xyz",
                "stream": "/v1/jobs/job_abc123xyz/stream"
            }
        },
        "errors": null
    }
    ```

    Save this `job_id` - you'll use it to check the status and retrieve your results.
  </Step>

  <Step title="Get Job Results">
    Use the job ID to check the status:

    ```bash theme={null}
    curl https://api.tokenkit.co/v1/jobs/job_abc123xyz \
      -H "Authorization: Bearer sk_live_v1_your_key_here"
    ```

    When the job completes, you'll receive your results:

    ```json theme={null}
    {
      "data": {
        "job_id": "job_abc123xyz",
        "status": "succeeded",
        "outputs": [
          {
            "url": "https://static.tokenkit.co/outputs/image.jpg"
          }
        ]
      },
      "errors": null
    }
    ```
  </Step>
</Steps>


# Rate Limits
Source: https://docs.tokenkit.co/usage-limits

Understand TokenKit's rate limiting and how to manage your request limits

## How Rate Limits Work

TokenKit uses rate limiting to ensure system stability and fair usage across all users. Rate limits are measured in **Requests Per Minute (RPM)** and are tied to your account and API keys.

### Rate Limit Basics

* **Measured in RPM** - The service only tracks requests per minute
* **Tied to API keys** - Each API key has its own rate limit
* **Starting limit: 100 RPM** - All new accounts begin with 100 requests per minute

## Checking Your Rate Limit

To see your current RPM limit and monitor your API key usage:

<Card title="API Keys Dashboard" icon="key" href="https://www.tokenkit.co/platform/api-keys">
  View your rate limits and manage your API keys
</Card>

## Rate Limit Exceeded

If you exceed your rate limit, the API will respond with a `429 Too Many Requests` status code:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Request quota exceeded. Please try again later."
    }
  ]
}
```

<Warning>
  When you receive a 429 response, wait before retrying your request to avoid further rate limiting.
</Warning>

## Requesting Increased Limits

If your application needs a higher RPM limit, you can request an increase:

<Card title="Request Higher Limits" icon="envelope" href="https://www.tokenkit.co/platform/contact?subject=Request%20Increased%20Rate%20Limit">
  Submit the contact form in the developer platform
</Card>