RukPrompt

เอกสาร API สำหรับนักพัฒนา

RukPrompt API ให้คุณสร้างภาพด้วย AI จากแอปของคุณ ผ่าน HTTP request แบบ sync blocking (POST แล้วรอจน generate เสร็จ) โดยไม่ต้อง polling — เหมาะสำหรับ server-side integration, SDK, หรือ automation workflow

เริ่มใช้งาน API ฟรี

สมัคร workspace เพื่อสร้าง API key และเริ่ม generate ภาพ — ใช้เครดิตฟรีตั้งแต่สมัคร

เข้าสู่ระบบสมัครฟรี
Base URL
https://developer.rukprompt.com
Auth
Bearer sk-img-...
Max blocking time
180 วินาที (ถ้าเกินจะคืน 504 + jobId)

การยืนยันตัวตน (Authentication)

ทุก request ต้องมี header:

bash
Authorization: Bearer sk-img-<your-key>

• สมัครสมาชิก เพื่อสร้าง workspace — ได้เครดิตฟรีตั้งแต่เริ่ม

• เข้าไปที่ Settings → สำหรับนักพัฒนา ในหน้า workspace เพื่อสร้าง API key

• key จะแสดงครั้งเดียวตอนสร้าง — บันทึกไว้ใน password manager หรือ environment variable

• เครดิตตัดจาก workspace ของ key — ดูยอดได้จาก GET /v0/usage

สร้างภาพด้วย AI

POST
/v0/images/generations

สร้างภาพด้วย AI — รอสูงสุด 180 วินาที แล้วคืน URL ของภาพที่สร้างเสร็จทันที (sync blocking)

Example Request

cURL
curl -X POST https://developer.rukprompt.com/v0/images/generations \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat wearing sunglasses",
    "modelVersion": "gemini-2.5-flash-image",
    "resolution": "standard",
    "aspectRatio": "1:1",
    "sampleCount": 1
  }'

Request Body Parameters
คลิกช่องเพื่อแก้ค่า

promptstring
required
ข้อความอธิบายภาพที่ต้องการสร้าง — ใช้ภาษาอังกฤษหรือไทยก็ได้ แนะนำ 20-500 คำ
modelVersionstring
optional
Model ID — ดูรายการจาก GET /v0/models
resolution"low" | "standard" | "high" | "4k"
default: "standard"
optional
Resolution tier — เครดิตต่อภาพขึ้นกับ tier
aspectRatiostring
default: "1:1"
optional
สัดส่วนของภาพ — แต่ละ model อาจรองรับไม่ครบ
sampleCountinteger (1-4)
default: 1
optional
จำนวนภาพที่ต้องการ — เครดิตจะคูณตาม count
isPublicboolean
default: false
optional
การมองเห็นของภาพ —
• private (default): เห็นเฉพาะในทีมของคุณ
• public: โชว์ใน Community gallery — คนอื่นเห็นได้
response_format"url" | "b64_json" | "both"
default: "url"
optional
รูปแบบ response —
• url (default) คืนลิงก์ภาพ
• b64_json คืน base64 อย่างเดียว (เข้ากับ OpenAI)
• both คืนทั้ง url + base64
ส่งเป็น query (?response_format=b64_json) หรือใน body ก็ได้
asyncboolean
default: false
optional
ถ้า true — enqueue แล้ว return jobId ทันที (ไม่รอ) แล้วให้ poll ผ่าน GET /v0/images/generations/{jobId}
แนะนำสำหรับโมเดลที่ช้า (gpt-image-2 อาจเกิน 180s) หรืออยู่หลัง proxy ที่มี timeout สั้น
ใช้ตามต้องการ
negativePromptstring
optional
สิ่งที่ไม่อยากให้มีในภาพ (เฉพาะ Stable Diffusion models)
ใช้ตามต้องการ
presetIdstring
optional
ID ของ preset ที่จะใช้เป็น base prompt template
ใช้ตามต้องการ
variablesobject
optional
ค่าตัวแปรของ preset (ใช้ร่วมกับ presetId) — เช่น `{"product": "sneakers"}`
ใช้ตามต้องการ
refImageUrlsstring[]
optional
URL ของภาพอ้างอิง (public HTTP/HTTPS, max 5 ภาพ, 10MB/ภาพ) — ใช้ใน image-to-image
ใช้ตามต้องการ
refImageBase64{ mimeType, data }[]
optional
ภาพอ้างอิงแบบ base64 — ทางเลือกแทน refImageUrls (max 5 ภาพ, 10MB/ภาพ)
ใช้ตามต้องการ

Response (200 OK)

json
{
  "code": 200,
  "data": {
    "id": "job_abc123",           // jobId สำหรับ tracking
    "created": 1745000000,        // unix timestamp
    "model": "gemini-2.5-flash-image",
    "data": [
      {
        "id": "img_xyz",          // generated image id
        "url": "https://cdn.rukprompt.com/teams/.../abc.png",
        "storageKey": "teams/.../abc.png",
        // ถ้าส่ง ?response_format=b64_json หรือ both จะมี field เพิ่ม:
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "mimeType": "image/png"
      }
    ],
    "usage": {
      "credits": 1                // เครดิตที่ถูกตัดจาก team
    }
  }
}

ตรวจสอบสถานะ Job

GET
/v0/images/generations/:jobId

ใช้เมื่อ POST ได้ 504 timeout เพื่อเช็คว่า job เสร็จหรือยัง — คืนข้อมูลภาพเมื่อ status = completed

cURL
curl "https://developer.rukprompt.com/v0/images/generations/job_abc123" \
  -H "Authorization: Bearer sk-img-..."
Response shape เหมือน POST /v0/images/generationsแต่จะมี status field เพิ่ม:"waiting" | "processing" | "completed" | "failed"

รายการ AI Models ที่ใช้ได้

GET
/v0/models

ดูโมเดลทั้งหมด + ค่าเครดิตต่อภาพ + aspect ratios ที่แต่ละโมเดลรองรับ

cURL
curl "https://developer.rukprompt.com/v0/models" \
  -H "Authorization: Bearer sk-img-..."

Models ที่ใช้งานได้ในทีมของคุณ

กำลังโหลด models...

ตัวเลขคือเครดิตต่อ 1 ภาพ — ถ้า sampleCount = 4 จะคูณ 4

Presets (CRUD)

GET / POST / PATCH / DELETE
/v0/images/presets

จัดการ preset ของทีมผ่าน API key — สร้าง / แก้ไข / ลบ / ดู ได้เต็ม. AI agent (เช่น MCP) ก็เรียกชุดนี้เพื่อสร้าง preset อัตโนมัติได้

CRUD พร้อมใช้งาน
API key ของทีมสามารถสร้าง / แก้ไข / ลบ preset ของทีมตัวเองได้ — แต่ ห้ามแก้ preset ที่ import จาก Community (จะได้ HTTP 403)

1. List presets

cURL
curl "https://developer.rukprompt.com/v0/images/presets" \
  -H "Authorization: Bearer sk-img-..."

เพิ่ม ?teamOnly=true ใน URL ถ้าอยากได้เฉพาะ preset ของทีม (ไม่รวม public)

2. Get one preset

cURL
curl "https://developer.rukprompt.com/v0/images/presets/<presetId>" \
  -H "Authorization: Bearer sk-img-..."

3. Create preset (POST)

prompt ใช้ {{key}} placeholder ทุก {{key}} ต้องมี matching item ใน requirements. key ต้องเป็น snake_case ภาษาอังกฤษ. ใช้ {{#if key}}...{{/if}} สำหรับตัวแปร optional.

cURL
curl -X POST "https://developer.rukprompt.com/v0/images/presets" \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product Photography",
  "note": "ภาพโฆษณาสินค้าสไตล์ studio",
  "prompt": "ภาพถ่ายโฆษณาสินค้า {{product_name}} สำหรับกลุ่มเป้าหมาย {{target_audience}} สไตล์ {{art_style}}{{#if extra_note}}, {{extra_note}}{{/if}} คุณภาพสูง รายละเอียดชัดเจน",
  "requirements": [
    {
      "key": "product_name",
      "label": "ชื่อสินค้า",
      "type": "text",
      "required": true,
      "placeholder": "เช่น รองเท้าวิ่ง Nike Air Max"
    },
    {
      "key": "target_audience",
      "label": "กลุ่มเป้าหมาย",
      "type": "dropdown",
      "required": false,
      "defaultValue": "adults aged 25-45",
      "options": [
        {
          "label": "วัยรุ่น",
          "value": "teenagers aged 15-25"
        },
        {
          "label": "ผู้ใหญ่",
          "value": "adults aged 25-45"
        },
        {
          "label": "ผู้สูงอายุ",
          "value": "seniors aged 50+"
        }
      ]
    },
    {
      "key": "art_style",
      "label": "สไตล์ภาพ",
      "type": "text",
      "defaultValue": "minimalist"
    },
    {
      "key": "extra_note",
      "label": "หมายเหตุเพิ่มเติม",
      "type": "text",
      "required": false
    }
  ],
  "modelVersion": "gemini-2.5-flash-image",
  "lockModel": true,
  "defaultAspectRatio": "1:1",
  "tags": [
    "product",
    "studio",
    "advertising"
  ]
}'

4. Update preset (PATCH)

ส่งเฉพาะ field ที่ต้องการแก้ — version snapshot จะถูกสร้างอัตโนมัติทุกครั้งที่ update

cURL
curl -X PATCH "https://developer.rukprompt.com/v0/images/presets/<presetId>" \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product Photography v2",
  "note": "ปรับ prompt ให้เน้น dramatic lighting",
  "prompt": "ภาพถ่ายโฆษณาสินค้า {{product_name}} สไตล์ {{art_style}} แสง dramatic studio lighting{{#if extra_note}}, {{extra_note}}{{/if}}",
  "tags": [
    "product",
    "dramatic"
  ]
}'

5. Delete preset (DELETE)

cURL
curl -X DELETE "https://developer.rukprompt.com/v0/images/presets/<presetId>" \
  -H "Authorization: Bearer sk-img-..."

6. Use preset to generate

ส่ง presetId + variables เข้า /v0/images/generations

json
{
  "presetId": "<presetId>",
  "prompt": "",
  "variables": {
    "product_name": "Nike Air Zoom Pegasus",
    "target_audience": "adults aged 25-45",
    "art_style": "cinematic",
    "extra_note": "with motion blur effect"
  },
  "aspectRatio": "1:1",
  "sampleCount": 1
}

Response (สำหรับ POST / PATCH / GET single)

json
{
  "data": {
    "id": "preset_abc123",
    "name": "Product Photography",
    "note": "ภาพโฆษณาสินค้าสไตล์ studio",
    "modelVersion": "gemini-2.5-flash-image",
    "defaultAspectRatio": "1:1",
    "lockModel": true,
    "lockAspectRatio": false,
    "thumbnailUrl": null,
    "requirements": [
      { "key": "product_name", "label": "ชื่อสินค้า", "type": "text", "required": true },
      { "key": "target_audience", "label": "กลุ่มเป้าหมาย", "type": "dropdown",
        "options": [
          { "label": "ผู้ใหญ่", "value": "adults aged 25-45" }
        ]
      }
    ],
    "accessLevel": "FULL",
    "isCommunity": false,
    "categories": [],
    "originTeam": null,
    "createdAt": "2026-04-26T..."
  }
}

Note: response จะ ไม่ echo prompt template — เพื่อกัน leak template ระหว่างทีม

Reference เต็ม: /v0/developer-docs/presets (markdown ที่ AI scrape ได้ตรงๆ)

รายการรูปที่สร้างเสร็จ (List)

GET
/v0/images/library

ดึงรายการรูปทั้งหมดของทีม — paginated, กรองตาม preset หรือค้นหาจาก userPrompt ได้

cURL
curl "https://developer.rukprompt.com/v0/images/library?page=1&limit=20" \
  -H "Authorization: Bearer sk-img-..."

Query params (ทุกตัว optional):

  • page — เลขหน้า (default 1)
  • limit — จำนวนต่อหน้า 1–100 (default 20)
  • presetId — กรองเฉพาะรูปที่สร้างจาก preset นี้
  • search — ค้นหาจาก userPrompt + ชื่อ preset

Response

json
{
  "data": {
    "images": [
      {
        "id": "img_abc123",
        "url": "https://cdn.../image.webp",
        "thumbnailUrl": "https://cdn.../thumb.webp",
        "width": 1024,
        "height": 1024,
        "presetId": "preset_xyz",
        "modelVersion": "gemini-2.5-flash-image",
        "userPrompt": "ภาพถ่ายรองเท้าวิ่ง",
        "isPublic": false,
        "createdAt": "2026-04-26T..."
      }
    ],
    "total": 124,
    "page": 1,
    "limit": 20
  }
}

รายละเอียดรูป (Get One)

GET
/v0/images/library/:imageId

ดึง metadata + URL ของรูป 1 ใบ — ใช้เมื่อรู้ imageId แล้ว (เช่นจาก /generations response)

cURL
curl "https://developer.rukprompt.com/v0/images/library/<imageId>" \
  -H "Authorization: Bearer sk-img-..."

Response

json
{
  "data": {
    "id": "img_abc123",
    "presetId": "preset_xyz",
    "prompt": "rendered prompt with variables filled in",
    "userPrompt": "ภาพถ่ายรองเท้าวิ่ง",
    "modelVersion": "gemini-2.5-flash-image",
    "variables": { "product_name": "Nike Air Zoom" },
    "sourceType": null,
    "isPublic": false,
    "url": "https://cdn.../image.webp",
    "thumbnailUrl": "https://cdn.../thumb.webp",
    "width": 1024,
    "height": 1024,
    "createdAt": "2026-04-26T..."
  }
}

ดาวน์โหลดรูป (Binary)

GET
/v0/images/library/:imageId/download

ดาวน์โหลดไฟล์ binary โดยตรง — response เป็น Content-Disposition: attachment พร้อม filename

cURL
curl "https://developer.rukprompt.com/v0/images/library/<imageId>/download" \
  -H "Authorization: Bearer sk-img-..." \
  -o image.webp

Tip: ส่วนใหญ่ไม่ต้อง download เลย — ใช้ url จาก /library/:id ตรงๆ ก็ได้ (R2 public URL) เร็วกว่าและไม่ใช้ quota dev API

Endpoint นี้เหมาะกับกรณีที่ต้องการ bytes ใน server เช่นใส่ใน ZIP / re-upload ไป third party

MCP Server (สำหรับ AI Agent)

POST
/v0/mcp

Model Context Protocol — Claude Desktop / Cursor / MCP client เชื่อมตรงเข้ามาได้ ใช้ API key เดิม sk-img-...

MCP wraps endpoint ทั้งหมดข้างต้นเป็น 11 tools ที่ AI agent เรียกได้:
Presets: preset_list / preset_get / preset_create / preset_update / preset_delete
Images: image_generate / image_list / image_get / image_download
Models: model_list
Credits: credits_check (เช็คเครดิตคงเหลือก่อน generate)

✨ Recommended: ใช้ CLI (npx)

One command — install + ตั้ง key + เขียน config block ลง MCP client ทำให้พร้อมใช้งานเลย เลือก client ด้านล่างเพื่อให้คำสั่งอัปเดตให้ตรง

bash
npx -y @rukprompt/cli install claude-desktop --api-key sk-img-...

📝 Manual config (npx)

ถ้าอยาก paste config block เอง — ใช้ shape เดียวกันทุก client (Claude Desktop / Claude Code / Cursor)

json
{
  "mcpServers": {
    "rukprompt": {
      "command": "npx",
      "args": ["-y", "@rukprompt/cli", "mcp"],
      "env": { "RUKPROMPT_API_KEY": "sk-img-..." }
    }
  }
}

Direct CLI (terminal usage)

CLI มี sub-command ตรงกับ MCP tool — ใช้ใน terminal โดยไม่ต้องผ่าน MCP client เลย

bash
# Presets
rukprompt preset list --team-only
rukprompt preset create --name "Studio shot" --prompt "minimal product photo of {{product}}"

# Images
rukprompt image generate --prompt "a cat astronaut" --aspect 16:9 --out cat.png
rukprompt image list --limit 50

# Models / credits
rukprompt model list
rukprompt credits check

Key management

bash
rukprompt key set --api-key sk-img-...    # validate + persist
rukprompt key show                                # show masked key + last validated
rukprompt key test                                # ping backend
rukprompt key clear                               # remove from this machine
🔧 Advanced: Direct HTTP (base layer)

CLI เป็น proxy layer ที่ wrap HTTP MCP ที่ https://developer.rukprompt.com/v0/mcp. ถ้าอยาก connect ตรงๆ (เช่น runtime ที่ไม่มี Node.js) ก็ทำได้:

json
{
  "mcpServers": {
    "rukprompt": {
      "type": "http",
      "url": "https://developer.rukprompt.com/v0/mcp",
      "headers": { "Authorization": "Bearer sk-img-..." }
    }
  }
}

หมายเหตุ: ต้องมี "type": "http" สำหรับ Claude Code CLI (~/.claude.json) — ไม่งั้นจะเจอ error "Does not adhere to MCP server configuration schema"

Raw JSON-RPC (curl)
bash
curl -X POST https://developer.rukprompt.com/v0/mcp \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
MCP Inspector
bash
# ผ่าน CLI (stdio):
npx @modelcontextprotocol/inspector \
  --command "npx -y @rukprompt/cli mcp" \
  --env "RUKPROMPT_API_KEY=sk-img-..."

# หรือ direct HTTP:
npx @modelcontextprotocol/inspector \
  --url https://developer.rukprompt.com/v0/mcp \
  --header "Authorization: Bearer sk-img-..."

Reference เต็ม: /v0/developer-docs/mcp

ทุก tool call ของ MCP ถูก log ใน developer_api_usage เหมือน REST request

API Reference (สำหรับ AI / Developer)

GET
/v0/developer-docs

Markdown reference ที่ AI scrape อ่านได้โดยตรง + OpenAPI 3.0 spec ที่ generate client หรือ introspect ได้

Markdown Reference (text/markdown)

  • Getting Started — auth, base URL, endpoint map
  • Presets — schema, requirement types, conditional blocks, ตัวอย่าง CRUD
  • Image Generation — sync vs async, multipart, aspect ratios
  • Errors — รายการ HTTP code + retry policy
  • MCP Setup — Claude Desktop / Cursor config

OpenAPI 3.0 Spec

สำหรับ generate client ภาษาต่างๆ หรือใช้ใน Swagger UI / Postman / Insomnia:

bash
# Download OpenAPI spec (JSON)
curl https://developer.rukprompt.com/docs/developer.json > developer-api.json

# Generate TypeScript client (เช่น openapi-typescript)
npx openapi-typescript https://developer.rukprompt.com/docs/developer.json -o ./api-types.ts

เครดิตคงเหลือและประวัติการใช้

GET
/v0/usage

เครดิตคงเหลือของทีม + สถิติการใช้งาน + 50 jobs ล่าสุด

cURL
curl "https://developer.rukprompt.com/v0/usage?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer sk-img-..."

Query params (optional):

  • from — ISO date (start of range)
  • to — ISO date (end of range)

ประวัติการเรียก API

GET
/v0/history

ประวัติการเรียก API ทั้งหมดของทีม — กรองและแบ่งหน้าได้

cURL
curl "https://developer.rukprompt.com/v0/history?page=1&limit=20&status=success" \
  -H "Authorization: Bearer sk-img-..."

Query params:

  • page — default 1
  • limit — 1-100, default 20
  • status — "success" | "failed"
  • apiKeyId — filter เฉพาะ key
  • from / to — ISO date range

รหัส Error (Error Codes)

400
Bad Request
Parameter ไม่ถูกต้อง (prompt ว่าง, aspectRatio ไม่รองรับ, model invalid)
401
Unauthorized
ไม่มี Authorization header / key ไม่ถูกต้อง / key ถูก revoke
403
Forbidden
Team ไม่มีสิทธิ์ใช้ model นี้ (R18, premium) หรือ suspended
404
Not Found
jobId ไม่ใช่ของ team นี้ หรือ request host ไม่ใช่ developer.rukprompt.com
429
Too Many Requests
Rate limit 60 req/min per key หรือ planConcurrent reached
500
Internal Server Error
AI provider fail, storage error, unexpected exception
504 timeout
Gateway Timeout
Generation เกิน 180s — ใช้ jobId ที่ return มา poll ผ่าน GET endpoint หรือส่ง async:true เพื่อ return jobId ตั้งแต่แรก
Error response format:
json
{
  "code": 401,
  "message": "Invalid or revoked API key",
  "data": null
}