OpenAI Embeddings API Application and Usage

The OpenAI embedding service is used to generate embedding results representing input text.

This document mainly introduces the usage process of OpenAI Embeddings API operations. With it, we can create embedding vectors representing input text.

¶ Application Process

To use the OpenAI Embeddings API, first go to the 测试 Console to obtain your API Token and keep it as a backup.

If you have not yet logged in or registered, you will be automatically redirected to the login page, where you will be invited to register and log in. After completion, you will automatically return to the current page.

One API Token can be used to call all services on the platform; there is no need to apply separately for each service. Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.

📘 Full documentation: OpenAI Embeddings API →

¶ Basic Usage

Next, you can fill in the corresponding content in the interface, as shown in the image:

When using this API for the first time, we need to fill in at least three items. One is authorization, which can be selected directly from the dropdown list. Another parameter is model; model is the OpenAI official model type we choose to use. The currently available models are text-embedding-3-small and text-embedding-3-large. text-embedding-ada-002 is no longer available; if an existing vector index uses this old model, its vectors cannot be directly mixed with vectors from the new models, and the index needs to be rebuilt. The last parameter is input; input is the text for which we need to convert into embeddings.

At the same time, you can notice that there is corresponding generated invocation code on the right. You can copy the code and run it directly, or directly click the "Try" button for testing.

Optional parameters:

• dimensions: Trims the vector dimensions; the full dimensions are output by default.
• encoding_format: Return format, either float or base64.

Python sample invocation code:

import requests

url = "https://api.acedata.cloud/openai/embeddings"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-3-small",
    "encoding_format": "float"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

After the invocation, we find that the returned result is as follows:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0022756963,
        -0.009305916,
        0.015742613,
        -0.0077253063,
        -0.0047450014,
        0.014917395,
        -0.009807394,
        -0.038264707,
        -0.0069127847,
        -0.028590616,
        0.025251659,
        ....
        -0.014079482,
        -0.015425222,
        0.0040753055,
        0.002727979,
        -0.03138366,
        0.041159317,
        -0.017608874,
        -0.018637223,
        0.014587308,
        0.010486611,
        -0.015387135,
        -0.019424353,
        -0.002800979
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

The returned result contains multiple fields, described as follows:

• model, the model used for this text-to-embedding conversion.
• usage, the token information used for this text-to-embedding conversion.
• data, the embedding result after text conversion.

Among them, data contains the specific information about the embedding corresponding to the text, and its embedding is the specific generated embedding result.

¶ Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and information. For example:

• 400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token: Unauthorized, invalid or missing authorization token.
• 429 too_many_requests: Too many requests, you have exceeded the rate limit.
• 500 api_error: Internal server error, something went wrong on the server.

¶ Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

¶ Conclusion

Through this document, you have learned how to easily use the official OpenAI embedding generation functionality through the OpenAI Embeddings API. We hope this document helps you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.