API Reference

Krev API

Generate studio-quality product images, videos, ads, and async chat runs programmatically. Built for AI agents, automation tools, and custom integrations.

Base URLhttps://app.krev.ai/api/v1

v1.0

The Krev API lets you generate product images, create videos, generate ad creative, run async chat automations, browse your product catalog, send Meta conversion events, and check your credit balance. Most requests use JSON and authenticate via API key.

Responses always include a success boolean. On failure, an error string describes the issue. The machine-readable OpenAPI spec is available at /api/v1/openapi.json.

Authentication

Every request must include an API key in the Authorization header. Create a key from your Krev dashboard under Settings → API Keys.

Authorization Header

Authorization: Bearer sk_live_YOUR_KEY_SECRET

Keep your key secret. The full key is shown only once when created. If compromised, revoke it immediately from the dashboard and create a new one.

GETPOSTDELETE

API Keys

/api/v1/keys

Manage API keys from an authenticated dashboard session. These endpoints use your logged-in Krev session, not a bearer API key. New keys default to the full public scope set:images, videos, products,credits, ads, conversions, and chat.

Create Key

Request

POST https://app.krev.ai/api/v1/keys
Content-Type: application/json

{
  "name": "Automation key",
  "scopes": ["images", "videos", "products", "credits", "ads", "conversions", "chat"]
}

Revoke Key

Request

DELETE https://app.krev.ai/api/v1/keys?id=api_key_id

POST

Generate Images

/api/v1/images

Generate one or more AI product images. Supports text-to-image and image-to-image with product references. Credits are deducted automatically.

Request Body

Parameter	Type	Description
`prompt`required	string	Text prompt describing the image to generate.
`aspect_ratio`	string	One of "1:1", "16:9", "9:16", "4:3", "3:4".Default: `"1:1"`
`product_id`	uuid	Product ID to use as a reference (from GET /products).
`product_ids`	uuid[]	Multiple product IDs for multi-product scenes.
`preset_id`	string	Studio preset ID for styling (e.g. flat_lay, lifestyle).
`hd`	boolean	Enable 4K upscaling. Costs 2x credits.Default: `false`
`image_count`	integer	Number of variants to generate. One of 1, 2, or 4.Default: `1`
`reference_images`	string[]	External image URLs for style reference.

Example Request

cURL

curl -X POST https://app.krev.ai/api/v1/images \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Premium leather wallet on dark marble surface, studio lighting",
    "aspect_ratio": "1:1",
    "image_count": 2
  }'

Example Response

200 OK

{
  "success": true,
  "data": {
    "generation_id": "a1b2c3d4-...",
    "images": [
      "https://app.krev.ai/storage/gen/img_001.webp",
      "https://app.krev.ai/storage/gen/img_002.webp"
    ],
    "image_count": 2,
    "credits_used": 80
  }
}

POST

Generate Video

/api/v1/videos

Generate a short product or creator-style video. Krev routes between Seedance text-to-video, reference-to-video, image-to-video, and a dedicated UGC workflow based on your prompt and available references. Credits are deducted from your account.

Request Body

Parameter	Type	Description
`prompt`required	string	Text prompt describing the video scene.
`aspect_ratio`	string	One of "1:1", "16:9", "9:16", "4:3", "3:4".Default: `"16:9"`
`duration`	integer	Video duration in seconds. Any integer from 4 to 15.Default: `5`
`audio_mode`	string	One of "auto", "off", or "native". Audio does not change pricing.Default: `"auto"`
`product_id`	uuid	Product ID for product-led video generation. Krev can use the product images as references.
`source_image`	string (URL)	External image URL to animate directly. Video URLs are not supported here.
`preset_id`	string	Studio preset ID for styling.

Example Request

cURL

curl -X POST https://app.krev.ai/api/v1/videos \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Smooth camera pan around sneakers with soft lighting",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

Example Response

200 OK

{
  "success": true,
  "data": {
    "generation_id": "e5f6g7h8-...",
    "video_url": "https://app.krev.ai/storage/gen/vid_001.mp4",
    "duration": 5,
    "credits_used": 400
  }
}

GET

List Products

/api/v1/products

Returns all products in your catalog with signed image URLs. Pass an id query param to fetch a single product.

Query Parameters

Parameter	Type	Description
`id`	uuid	Get a single product by ID.
`limit`	integer	Max products to return (max 100).Default: `50`

Example Request

cURL

curl https://app.krev.ai/api/v1/products?limit=10 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Example Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "d1e2f3a4-...",
      "name": "Leather Crossbody Bag",
      "image_url": "https://app.krev.ai/storage/products/bag.webp",
      "category": "bags",
      "metadata": { "color": "tan" },
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": { "count": 1 }
}

POST

Upload Product

/api/v1/products

Upload a product image to run the full analysis pipeline: background removal, AI metadata extraction (brand, product type, colors, materials), and auto-naming. The product is stored in your catalog and its id can be used for image and video generation.

Body Parameters (JSON)

Parameter	Type	Description
`image_url`required	string	Public URL of the product image, or a base64 data URL.
`name`	string	Product name. Auto-generated from AI analysis if omitted.
`skip_segmentation`	boolean	Skip background removal for faster processing.Default: `false`

Also accepts multipart/form-data with a file field instead of image_url. Supported types: JPG, PNG, WebP.

Example Request

cURL (JSON)

curl -X POST https://app.krev.ai/api/v1/products \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product.jpg",
    "name": "Premium Leather Wallet"
  }'

cURL (File Upload)

curl -X POST https://app.krev.ai/api/v1/products \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "file=@product.jpg" \
  -F "name=Premium Leather Wallet"

Example Response

200 OK

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Day Shift by Vysionary",
    "image_url": "https://app.krev.ai/storage/...",
    "segmented_image_url": "https://app.krev.ai/storage/...",
    "category": null,
    "metadata": {
      "brandName": "Vysionary",
      "productName": "Day Shift",
      "productType": "supplement",
      "colors": ["black", "gold"],
      "materials": ["plastic bottle"]
    },
    "source": "api",
    "created_at": "2026-02-25T23:00:00Z"
  }
}

POST

Generate Ads

/api/v1/ads

Generate performance ad creative from one or more products. This endpoint uses the same ad generation logic as the Krev app and returns generated images plus ad copy.

Request Body

Parameter	Type	Description
`brief`required	string	Creative brief for the ad.
`product_ids`required	uuid[]	One or more product IDs to feature.
`aspect_ratio`	string	One of "1:1", "4:5", "9:16".Default: `"4:5"`
`image_count`	integer	Number of ad image variants to generate. One of 1, 2, or 4.Default: `1`
`style_id`	string	Optional ad style or template preference.
`inspiration_image`	string (URL)	Optional ad image URL to use as inspiration.
`brand_context`	string	Optional brand notes for the ad.

Example Request

cURL

curl -X POST https://app.krev.ai/api/v1/ads \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Create a direct response ad for this protein bar",
    "product_ids": ["d1e2f3a4-..."],
    "aspect_ratio": "4:5",
    "image_count": 2
  }'

Example Response

200 OK

{
  "success": true,
  "data": {
    "generation_id": "a1b2c3d4-...",
    "images": [
      "https://app.krev.ai/storage/gen/ad_001.webp"
    ],
    "image_count": 1,
    "credits_used": 40,
    "ad_copy": {
      "style_name": "Performance Master",
      "hook": "Built for long days",
      "headline": "Protein that keeps up",
      "body_copy": "A clean bar for busy operators.",
      "cta": "Shop now"
    }
  }
}

POSTGET

Async Chat

/api/v1/chat

Queue a creative-only Krev agent run for automations. Chat runs are asynchronous. Start a run, then poll the returnedpoll_url for status, transcript, artifacts, and signed media URLs.

The public chat API supports products, credits, image and video generation, ad generation, and ad-library research. Meta campaign and account mutation requests return 403.

Start Chat Run

Parameter	Type	Description
`message`required	string	Instruction for the agent.
`conversation_id`	uuid	Existing API chat conversation to continue.
`product_ids`	uuid[]	Owned product IDs to include as selected context.
`reference_images`	string[]	External image URLs to include as visual references.
`agent`	string	One of "auto", "asset", or "discover".Default: `"auto"`

cURL

curl -X POST https://app.krev.ai/api/v1/chat \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Make three ad concepts for this product and include image ideas",
    "product_ids": ["d1e2f3a4-..."],
    "agent": "asset"
  }'

Queued Response

202 Accepted

{
  "success": true,
  "data": {
    "conversation_id": "conversation-uuid",
    "user_message_id": "message-uuid",
    "assistant_message_id": "message-uuid",
    "run_id": "run-uuid",
    "job_id": "job-uuid",
    "status": "queued",
    "poll_url": "https://app.krev.ai/api/v1/chat/runs/run-uuid"
  }
}

Poll Run

cURL

curl https://app.krev.ai/api/v1/chat/runs/run-uuid \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Run polling returns owner-checked run and job status, latest assistant text, transcript messages, sanitized artifacts, generation IDs, generation records, and signed media URLs when available.

Conversation History

cURL

curl https://app.krev.ai/api/v1/chat/conversations/conversation-uuid \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

POST

Meta Conversions

/api/v1/conversions/meta

Send server-side Meta conversion events through your connected Meta pixel. This endpoint requires the conversionsscope and an active Meta pixel configuration.

Example Request

cURL

curl -X POST https://app.krev.ai/api/v1/conversions/meta \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "Purchase",
    "event_time": 1777632000,
    "event_id": "order_123",
    "action_source": "website",
    "event_source_url": "https://example.com/products/wallet",
    "user_data": {
      "email": "customer@example.com"
    },
    "custom_data": {
      "currency": "USD",
      "value": 79.00
    }
  }'

Example Response

200 OK

{
  "success": true,
  "status": "sent",
  "events_received": 1
}

GET

Generation Status

/api/v1/generations/{id}

Poll a generation to check its status and retrieve output URLs when complete. Use the generation_id returned from the image or video endpoints.

Path Parameters

Parameter	Type	Description
`id`required	uuid	Generation ID returned from the image or video endpoint.

Status Values

Status	Description
`queued`	Waiting to start processing.
`processing`	Actively generating. Check `progress` (0-100).
`succeeded`	Complete. Output URLs are available in `output`.
`failed`	Generation failed. Check `error` for details.

Example Request

cURL

curl https://app.krev.ai/api/v1/generations/a1b2c3d4-... \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Example Response

200 OK

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "kind": "image",
    "status": "succeeded",
    "progress": 100,
    "output": {
      "urls": [
        "https://app.krev.ai/storage/gen/img_001.webp"
      ]
    },
    "error": null,
    "created_at": "2026-02-14T12:00:00Z",
    "completed_at": "2026-02-14T12:00:45Z"
  }
}

GET

Check Credits

/api/v1/credits

Returns your current credit balance, plan info, and storage usage. Useful for checking remaining capacity before queuing generations.

Example Request

cURL

curl https://app.krev.ai/api/v1/credits \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Example Response

200 OK

{
  "success": true,
  "data": {
    "plan": "pro",
    "plan_name": "Pro",
    "credits": {
      "current": 1840,
      "limit": 2500,
      "current_formatted": "1,840",
      "limit_formatted": "2,500"
    },
    "storage": {
      "used_bytes": 524288000,
      "limit_bytes": 2147483648,
      "used_formatted": "500 MB",
      "limit_formatted": "2 GB"
    },
    "resets_at": "2026-03-01T00:00:00Z"
  }
}

Error Codes

All error responses follow the same shape. The success field is false and an error string describes the issue.

Error Response Shape

{
  "success": false,
  "error": "Description of what went wrong"
}

Status	Meaning	Common Cause
`400`	Bad Request	Missing or invalid parameters (e.g. no prompt).
`401`	Unauthorized	Missing, invalid, or expired API key.
`402`	Payment Required	Insufficient credits for the requested generation.
`404`	Not Found	Resource not found (e.g. invalid generation ID).
`429`	Too Many Requests	Rate limit exceeded. Wait and retry.
`500`	Server Error	Unexpected internal error. Credits are automatically refunded.

Credit Costs

API calls consume the same credits as the Krev dashboard. Check your balance with GET /credits before generating.

Operation	Credits	Notes
Standard image	40	Per image. Multiply by `image_count`.
4K image (hd: true)	80	Per image. 2x standard cost.
5-second video	400	Video pricing scales at about 80 credits per second. Audio does not change price.
10-second video	800	Same per-second pricing. Useful for longer story-led or creator-style cuts.
15-second video	1200	Current max duration on the public API.

If a generation fails, credits are automatically refunded to your account. Video pricing scales with duration from 4 to 15 seconds.

Rate Limits

API keys share the same rate limits as your Krev dashboard account. Limits are enforced per-user, not per-key.

When rate-limited, you will receive a 429 response. Wait a few seconds and retry. We recommend implementing exponential backoff in your integration.

Need higher throughput? Contact us at contact@krev.ai for enterprise limits.

Ready to integrate?

Create your API key in the Krev dashboard under Settings → API Keys, or reach out at contact@krev.ai.

Ship 10x More Creatives. Spend 90% Less.

Product photos, video ads, and copy. All from one platform, ready in minutes.

Get Started