AI Models API

Text and image generation over a single HTTP endpoint. No SDK, no keys to pass — just hit the URLs below.

\n\n

Base URL

All routes are relative to the deployment origin:

loading…

\n\n

Quick start

The fastest way to see it work — open this in your browser:

loading…

\n\n \n

Chat

Send a prompt, get text back. There are two ways to call it.

\n\n

\n GET\n /v1/chat?prompt=...\n

Good for quick tests and simple one-liners. Put your question in the prompt query parameter.

curl \"$BASE/v1/chat?prompt=What%20is%20the%20capital%20of%20France%3F\"

\n\n

\n POST\n /v1/chat\n

Use this when you want a system prompt, a full conversation, or generation settings. Send JSON.

\n\n

Body fields

\n \n \n \n \n \n \n \n \n

Field	Type	Notes
`prompt`	string	Shortcut for a single user message. Use this or `messages`.
`messages`	array	Full chat history. Each item is `{ \"role\": \"system\" \| \"user\" \| \"assistant\", \"content\": \"...\" }`.
`model`	string	optional · defaults to `openai/gpt-oss-120b:groq`
`temperature`	number	optional · 0–2, higher is more random
`max_tokens`	number	optional · cap on response length
`top_p`	number	optional · nucleus sampling

\n\n

Example — single prompt

curl -X POST \"$BASE/v1/chat\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"Give me three names for a coffee shop.\"\n  }'

\n\n

Example — full conversation

curl -X POST \"$BASE/v1/chat\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"openai/gpt-oss-120b:groq\",\n    \"temperature\": 0.7,\n    \"messages\": [\n      { \"role\": \"system\", \"content\": \"You answer in one short sentence.\" },\n      { \"role\": \"user\", \"content\": \"Why is the sky blue?\" }\n    ]\n  }'

\n\n

Response

{\n  \"model\": \"openai/gpt-oss-120b\",\n  \"reply\": \"Sunlight scatters off air molecules, and blue light scatters most.\",\n  \"usage\": {\n    \"prompt_tokens\": 24,\n    \"completion_tokens\": 14,\n    \"total_tokens\": 38\n  }\n}

\n\n \n

Image

\n Describe an image, get back a hosted URL you can drop into an <img> tag.\n The server generates the image, uploads it for you, and returns the link.\n

\n\n

\n GET\n /v1/image?prompt=...\n

\n POST\n /v1/image\n

\n\n

Body / query fields

\n \n \n \n \n \n \n

Field	Type	Notes
`prompt`	string	What you want to see. Required.
`model`	string	optional · defaults to `Tongyi-MAI/Z-Image-Turbo`
`negative_prompt`	string	optional · things to avoid in the image
`raw`	boolean	optional · if true, returns the raw image bytes instead of a JSON URL

\n\n

Example

curl -X POST \"$BASE/v1/image\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"An astronaut riding a horse, cinematic lighting\"\n  }'

\n\n

Response

{\n  \"prompt\": \"An astronaut riding a horse, cinematic lighting\",\n  \"model\": \"Tongyi-MAI/Z-Image-Turbo\",\n  \"url\": \"https://jerrycans-file.hf.space/files/gen-1717000000000.png\",\n  \"content_type\": \"image/png\"\n}

\n\n

Want the image bytes directly (e.g. to pipe into a file)? Add ?raw=true:

curl \"$BASE/v1/image?prompt=a%20red%20bicycle&raw=true\" --output bike.png

\n\n \n

Calling it from code

\n\n

JavaScript

const base = \"$BASE\";\n\n// chat\nconst chat = await fetch(`${base}/v1/chat`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ prompt: \"Write a haiku about the sea.\" }),\n}).then(r => r.json());\nconsole.log(chat.reply);\n\n// image\nconst img = await fetch(`${base}/v1/image`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ prompt: \"A lighthouse at dusk\" }),\n}).then(r => r.json());\nconsole.log(img.url);

\n\n

Python

import requests\n\nbase = \"$BASE\"\n\nchat = requests.post(f\"{base}/v1/chat\", json={\n    \"prompt\": \"Explain gravity to a five year old.\"\n}).json()\nprint(chat[\"reply\"])\n\nimg = requests.post(f\"{base}/v1/image\", json={\n    \"prompt\": \"A fox in a snowy forest\"\n}).json()\nprint(img[\"url\"])

\n\n \n

Errors

Failures come back as JSON with the matching HTTP status:

{\n  \"error\": \"Provide a 'prompt' describing the image\",\n  \"detail\": null\n}

\n \n \n \n \n \n \n \n

Status	Meaning
`400`	Bad input — missing prompt, malformed JSON, etc.
`404`	Route doesn't exist.
`405`	Wrong HTTP method for that route.
`429`	Rate limited upstream — slow down and retry.
`5xx`	Model or upload host had a problem. The `detail` field usually says what.

\n\n

Endpoints at a glance

\n \n \n \n \n \n \n

Route	Method	Does
`/`	GET	This page.
`/health`	GET	Liveness check.
`/v1/chat`	GET / POST	Text generation.
`/v1/image`	GET / POST	Image generation → hosted URL.

\n\n

\n\n\n\n\n\n",[96],{"_35":95,"_13":96,"_64":97,"_66":-5,"_67":68,"_69":98,"_71":72,"_37":116,"_17":31,"_74":24,"_76":100,"_78":50,"_79":-5,"_107":117,"_18":118},{"_35":89,"_13":90,"_64":91,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":113,"_17":33,"_74":75,"_76":93,"_78":50,"_79":-5,"_107":114,"_18":115},{"_35":81,"_13":82,"_64":83,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":110,"_17":33,"_74":85,"_76":86,"_78":50,"_79":87,"_107":111,"_18":112},{"_35":62,"_13":63,"_64":65,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":106,"_17":33,"_74":75,"_76":77,"_78":50,"_79":-5,"_107":108,"_18":109},["D",1780525450283],"children",[],[63],["D",1780525450283],[],[82],["D",1780525450283],[],[90],["D",1780525489226],[],[96],"368b93f9-a5ff-462e-99b6-79c9659d931b",["D",1780525450283],"legacyEnvVars","httpPrivacy","description","Simple JSON API endpoint","imageUrl","userId","0174c208-402b-421a-b569-545bcc2ed3a7","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount","019e8f95-5f18-718c-ba7f-c30626a1f06e","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_11":12,"_161":19},"org",{"_11":12,"_156":19,"_157":19,"_126":127,"_158":159,"_160":50},"branch",{"_17":98,"_13":16,"_35":68,"_41":119,"_44":36,"_45":43,"_153":52,"_154":42,"_155":56,"_57":14,"_53":12},"forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","displayName","avatar","tier","free","canRestrictVals","profileImageUrl","adoptOrgId",{"_35":119,"_13":14,"_37":216,"_48":-5,"_121":50,"_51":52,"_122":52,"_123":124,"_125":-5,"_126":127,"_128":83,"_129":72,"_130":-5,"_131":-5,"_132":33,"_55":133,"_134":-5,"_135":-5,"_136":-5,"_137":-5,"_138":139,"_140":139,"_141":142,"_143":142,"_144":142,"_145":139,"_146":139,"_147":217,"_149":218,"_151":219,"_49":50},[204,205,206,207],"files",[204,205,206,207],"counts",{"_194":33,"_195":70,"_196":33,"_34":197,"_198":199},[186,187,188,189],"upstreamProject",{"_35":42,"_13":14,"_123":124,"_125":-5,"_51":52,"_147":184},"upstreamBranch",{"_35":36,"_37":182,"_39":183,"_13":16,"_41":42,"_17":43,"_44":-5,"_45":-5,"_46":47,"_48":-5,"_49":50,"_51":52,"_53":54,"_55":56,"_57":14},"emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},["D",1780519334645],["D",1780525142664],{"_11":54,"_161":185},"https://lh3.googleusercontent.com/a/ACg8ocIuS4-SwJiruuCEmR_xeJNChwrND1xAByncZGFgp2IbjLxu2A=s96-c",{"_35":95,"_13":96,"_64":97,"_66":-5,"_67":68,"_69":98,"_71":72,"_37":99,"_17":31,"_74":24,"_76":100,"_78":50,"_79":-5,"_18":193},{"_35":89,"_13":90,"_64":91,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":92,"_17":33,"_74":75,"_76":93,"_78":50,"_79":-5,"_18":192},{"_35":81,"_13":82,"_64":83,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":84,"_17":33,"_74":85,"_76":86,"_78":50,"_79":87,"_18":191},{"_35":62,"_13":63,"_64":65,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":73,"_17":33,"_74":75,"_76":77,"_78":50,"_79":-5,"_18":190},[63],[82],[90],[96],"pulls","branches","forks",{"_200":202,"_203":33},"connections",{"_200":33,"_201":33},"count","unfilledCount",2,"emptyCount",{"_35":95,"_13":96,"_64":97,"_66":-5,"_67":68,"_69":98,"_71":72,"_37":116,"_17":31,"_74":24,"_76":100,"_78":50,"_79":-5,"_107":214,"_18":215},{"_35":89,"_13":90,"_64":91,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":113,"_17":33,"_74":75,"_76":93,"_78":50,"_79":-5,"_107":212,"_18":213},{"_35":81,"_13":82,"_64":83,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":110,"_17":33,"_74":85,"_76":86,"_78":50,"_79":87,"_107":210,"_18":211},{"_35":62,"_13":63,"_64":65,"_66":-5,"_67":68,"_69":70,"_71":72,"_37":106,"_17":33,"_74":75,"_76":77,"_78":50,"_79":-5,"_107":208,"_18":209},[],[63],[],[82],[],[90],[],[96],["D",1780525450283],{"_11":12,"_161":19},{"_11":12,"_156":19,"_157":19,"_126":127,"_158":159,"_160":50},{"_17":98,"_13":16,"_35":68,"_41":119,"_44":36,"_45":43,"_153":52,"_154":42,"_155":56,"_57":14,"_53":12},"ctx",{"_147":-5,"_179":253,"_254":255,"_256":257,"_258":50,"_259":50,"_260":50,"_261":72,"_262":-5,"_263":-7,"_264":-7,"_265":33,"_266":50,"_267":50,"_268":-5,"_269":50,"_270":50,"_271":50,"_272":-5},"ENV",{"_224":225,"_226":227,"_228":16,"_229":230,"_231":232,"_233":234,"_235":236,"_237":238,"_239":240,"_241":242,"_243":244,"_245":246,"_247":248,"_249":250,"_251":252},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Code