ImageToPrompts
Turn reference images into AI image-generation prompts via MCP. Check credits, submit a task, and retrieve its result. Requires an account API token.
Server MCP Terhosting
npx add-mcp 'https://imagetoprompts.io/api/mcp'Terpasang ke Claude Code, Codex, Cursor, dan lainnya
Dokumentasi
Availability: The remote MCP server and REST API are available to signed-in users with an account token. The local npm package is not published yet.
Generation will use account credits. Checking your balance or task status will not consume credits. Website daily free uses will not apply to API calls.
How connection will work
- Sign in to your ImageToPrompts account.
- Create an API token in your account settings.
- Add the remote MCP URL and your account token to a client that supports custom Authorization headers.
Remote MCP endpoint: https://imagetoprompts.io/api/mcp (Streamable HTTP). Example client configuration:
{
"mcpServers": {
"imagetoprompts": {
"url": "https://imagetoprompts.io/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Keep your token in the client configuration, never in a prompt or URL. Client configuration formats differ. The remote server accepts a public image URL or base64 data URL; it cannot read a local image path.
MCP tools
get_usage Free · 0 credits · Read-only
get_usage — check your account credit balance and current generation cost.
Input parameters: No input parameters required.
{}
{
"balance": 120,
"imageToPromptCredits": 2
}
image_to_prompt Uses account credits · Idempotent
image_to_prompt — submit an image and receive a task ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Required | Public image URL or base64 data URL (up to 15 MB). |
request_id | string | Required | 8–80 characters (letters, digits, _ or -; UUID recommended). Reuse the same key and arguments when retrying after a timeout to avoid double charging. |
style | enum | Optional | Target model style: natural (default), midjourney, flux, stable-diffusion, dalle. |
prompt_type | enum | Optional | Output structure: general (default), structured, json. |
language | string | Optional | Output language code, e.g. en (default), zh, ja, es, de. |
{
"image": "https://example.com/reference.webp",
"request_id": "req_20261113_a8f9c2d1",
"style": "flux",
"prompt_type": "structured",
"language": "en"
}
{
"taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "submitting"
}
get_task Free · 0 credits · Read-only
get_task — check the task and read its completed prompt.
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string (UUID) | Required | Task UUID returned by image_to_prompt. Poll at least 3 seconds apart; only tasks created via API by your account are accessible. |
{
"task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
{
"task": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"prompt": "A cinematic editorial portrait in soft natural window light, shallow depth of field, crisp fabric texture...",
"style": "flux",
"promptType": "structured"
}
}
REST API endpoints & calling examples
All MCP tools call the v1 REST API over HTTPS using your Bearer token (Authorization: Bearer i2p_...). You can also call these 3 endpoints directly from your own backend or scripts.
GET /api/v1/usage Free · 0 credits · Read-only
get_usage — check your account credit balance and current generation cost.
curl -X GET "https://imagetoprompts.io/api/v1/usage" \
-H "Authorization: Bearer i2p_your_api_token"
POST /api/v1/image-to-prompt Uses account credits · Idempotent
image_to_prompt — submit an image and receive a task ID.
curl -X POST "https://imagetoprompts.io/api/v1/image-to-prompt" \
-H "Authorization: Bearer i2p_your_api_token" \
-H "Idempotency-Key: req_20261113_a8f9c2d1" \
-H "Content-Type: application/json" \
-d '{
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"style": "midjourney",
"promptType": "general",
"promptLanguage": "en"
}'
GET /api/v1/tasks/{taskId} Free · 0 credits · Read-only
get_task — check the task and read its completed prompt.
curl -X GET "https://imagetoprompts.io/api/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Authorization: Bearer i2p_your_api_token"
Billing, idempotency & security rules
Credits & automatic refunds
Only image_to_prompt deducts account credits (website daily free uses do not apply). If upstream generation fails, credits are refunded automatically. Calling get_usage and get_task is free.
Idempotent retries
Every image_to_prompt call requires a request_id (or Idempotency-Key header). Retrying a timed-out request with the same key and payload returns the existing task without charging again.
Token security
Up to 5 active tokens per account, valid for 90 days. Only SHA-256 hashes are stored on the server. Rotating a token invalidates the previous secret immediately while preserving task ownership.