Generate An Image
This guide will walk you through how to generate an image using Core3D's API via HTTP requests.
Note: You'll need an API token to perform any of these actions. See the Authentication section of the API Reference. We'll use
$TOKEN
as a placeholder for your API token in the examples below.
Contents
- Step 1 — Pick A Style
- Step 2 — Create a Generation
- Step 3 — Check The Status
- Step 4 — View The Results
Step 1 — Pick A Style
We need to pick the style of image we want to generate. Let's make a request to the API to see what styles are available.
Request
$ curl https://api.core3d.io/v1/generation-styles \
-H "Authorization: Bearer $TOKEN"
Response
[
{
"id": "abstract-shapes",
"name": "Abstract Shapes",
"preview": "https://api.core3d.io/static/generation-styles/abstract-shapes.png",
"types": {
"pattern": {
"supports": []
}
},
"uri": "core3d:generation-style:abstract-shapes"
},
// ... additional results omitted
{
"id": "vector-art",
"name": "Vector Art",
"preview": "https://api.core3d.io/static/generation-styles/vector-art.png",
"types": {
"graphic": {
"supports": [
"prompt",
"transparency"
]
},
"pattern": {
"supports": [
"prompt"
]
}
},
"uri": "core3d:generation-style:vector-art"
}
]
The "Vector Art" style supports both graphic
and pattern
image generation types, so we'll choose that one. Take note of the ID, vector-art
, we'll need that in the next step. Also note that both target types support a prompt
input, which allows you to customize the image. Some styles also support a transparency
parameter which generates a PNG with the background already removed.
Step 2 — Create a Generation
We're ready to create an image generation, let's create a cat pattern in black and gold.
Request
$ curl -X POST https://api.core3d.io/v1/generations \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "image",
"data": {
"colors": ["black", "gold"],
"prompt": "lazy cats",
"style": "vector-art",
"type": "pattern"
}
}'
Response
{
// ... additional properties omitted
"id": "018d7045-4f7e-7ce0-830f-14c7f10a86b8",
"uri": "core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8",
"result": null,
"status": "pending"
}
Great! Our generation has been created and has a pending
status. Make note of the uri
property, we'll need it in the next step.
Step 3 — Check The Status
We can poll the API using the id
from the last request until the generation is complete. The status
will change from "pending" to "running", and we'll know it's done when the status
property reads "ok". If the status
reads "error", something went wrong.
Request
# For convenience, you can use a URI as the ID parameter in API requests
$ curl https://api.core3d.io/v1/generations/core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8 \
-H "Authorization: Bearer $TOKEN"
Response
{
// ... additional properties omitted
"id": "018d7045-4f7e-7ce0-830f-14c7f10a86b8",
"uri": "core3d:generation:018d7045-4f7e-7ce0-830f-14c7f10a86b8",
"result": {
"uploads": [
"core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8"
]
},
"status": "ok"
}
The generation is done! Let's view the results.
Step 4 — View The Results
We can make an additional request for each item in the result.uploads
property to generate a presigned URL that we can use to display or download the image -- the url
property of the response is what we want.
Request
# For convenience, you can use a URI as the ID parameter in API requests
$ curl https://api.core3d.io/v1/uploads/core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8 \
-H "Authorization: Bearer $TOKEN"
Response
{
// ... additional properties omitted
"id": "018d7045-c918-7add-921f-9fd36a42e5d8",
"uri": "core3d:upload:018d7045-c918-7add-921f-9fd36a42e5d8",
"url": "https://static.production.core3d.io/..."
}
And the result is...
Cool, abstract, I like it. Check out the next guide to turn this into a real design.